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

browser_cli/commands/doctor.py

@@ -0,0 +1,336 @@
+"""Install and runtime diagnostics for Browser CLI environments."""
+
+from __future__ import annotations
+
+import importlib.util
+import os
+import shutil
+import sys
+from argparse import Namespace
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any
+
+from browser_cli.automation.service.client import (
+    _probe_automation_service,
+    read_automation_service_run_info,
+)
+from browser_cli.constants import AppPaths, get_app_paths
+from browser_cli.daemon.client import run_info_is_compatible, send_command
+from browser_cli.daemon.transport import probe_socket, read_run_info
+from browser_cli.outputs.json import render_json_payload
+
+LOCK_FILES = ("SingletonLock", "SingletonCookie", "SingletonSocket")
+
+
+@dataclass(slots=True, frozen=True)
+class DoctorCheck:
+    id: str
+    status: str
+    summary: str
+    details: str | None = None
+    next: str | None = None
+
+
+def run_doctor_command(args: Namespace) -> str:
+    report = collect_doctor_report()
+    if getattr(args, "json", False):
+        return render_json_payload({"ok": True, "data": report, "meta": {"action": "doctor"}})
+    return render_doctor_report(report)
+
+
+def collect_doctor_report() -> dict[str, Any]:
+    app_paths = get_app_paths()
+    daemon_payload = _daemon_runtime_payload()
+    checks = [
+        _package_check(),
+        _chrome_check(),
+        _playwright_check(),
+        _home_check(app_paths),
+        _managed_profile_check(),
+        _daemon_check(app_paths),
+        _automation_service_check(app_paths),
+        _extension_check(daemon_payload),
+    ]
+    overall_status = "pass"
+    if any(item.status == "fail" for item in checks):
+        overall_status = "fail"
+    elif any(item.status == "warn" for item in checks):
+        overall_status = "warn"
+    return {
+        "overall_status": overall_status,
+        "checks": [asdict(item) for item in checks],
+    }
+
+
+def render_doctor_report(report: dict[str, Any]) -> str:
+    lines = [f"Doctor: {report['overall_status']}", ""]
+    for check in report["checks"]:
+        details = f" ({check['details']})" if check.get("details") else ""
+        lines.append(f"{check['id']}: {check['status']} - {check['summary']}{details}")
+        if check.get("next"):
+            lines.append(f"Next: {check['next']}")
+        lines.append("")
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def _package_check() -> DoctorCheck:
+    entrypoint = importlib.util.find_spec("browser_cli")
+    if entrypoint is None:
+        return DoctorCheck(
+            id="package",
+            status="fail",
+            summary="Python package import failed.",
+            next=(
+                "reinstall browser-control-and-automation-cli in this Python environment "
+                "and re-run browser-cli doctor"
+            ),
+        )
+    return DoctorCheck(
+        id="package",
+        status="pass",
+        summary="Python package import works.",
+    )
+
+
+def _chrome_check() -> DoctorCheck:
+    try:
+        executable = _discover_chrome_executable()
+    except Exception as exc:
+        return DoctorCheck(
+            id="chrome",
+            status="fail",
+            summary="Stable Google Chrome was not found.",
+            details=str(exc),
+            next="install stable Google Chrome and re-run browser-cli doctor",
+        )
+    return DoctorCheck(
+        id="chrome",
+        status="pass",
+        summary="Stable Google Chrome was found.",
+        details=str(executable),
+    )
+
+
+def _playwright_check() -> DoctorCheck:
+    if importlib.util.find_spec("playwright") is None:
+        return DoctorCheck(
+            id="playwright",
+            status="fail",
+            summary="Playwright Python package is not installed.",
+            next=(
+                "reinstall browser-control-and-automation-cli with uv tool install "
+                "--reinstall browser-control-and-automation-cli, or run uv sync --dev "
+                "in a repository checkout, then re-run browser-cli doctor"
+            ),
+        )
+    return DoctorCheck(
+        id="playwright",
+        status="pass",
+        summary="Playwright Python package import works.",
+    )
+
+
+def _home_check(app_paths: AppPaths) -> DoctorCheck:
+    if not app_paths.home.exists():
+        return DoctorCheck(
+            id="home",
+            status="fail",
+            summary="Browser CLI home does not exist yet.",
+            details=str(app_paths.home),
+            next="create the Browser CLI home directory or run a Browser CLI command that initializes it, then re-run browser-cli doctor",
+        )
+    if not _is_writable_directory(app_paths.home):
+        return DoctorCheck(
+            id="home",
+            status="fail",
+            summary="Browser CLI home is not writable.",
+            details=str(app_paths.home),
+            next="set BROWSER_CLI_HOME to a writable directory and re-run browser-cli doctor",
+        )
+    return DoctorCheck(
+        id="home",
+        status="pass",
+        summary="Browser CLI home is ready.",
+        details=str(app_paths.home),
+    )
+
+
+def _managed_profile_check() -> DoctorCheck:
+    profile_root = get_app_paths().home / "default-profile"
+    if not profile_root.exists():
+        return DoctorCheck(
+            id="managed_profile",
+            status="fail",
+            summary="Managed profile directory does not exist yet.",
+            details=str(profile_root),
+            next="run browser-cli read https://example.com once to initialize the managed profile, then re-run browser-cli doctor",
+        )
+    if not _is_writable_directory(profile_root):
+        return DoctorCheck(
+            id="managed_profile",
+            status="fail",
+            summary="Managed profile directory is not writable.",
+            details=str(profile_root),
+            next="fix permissions for the Browser CLI home directory and re-run browser-cli doctor",
+        )
+
+    lock_paths = [
+        profile_root / lock_name for lock_name in LOCK_FILES if (profile_root / lock_name).exists()
+    ]
+    if lock_paths:
+        return DoctorCheck(
+            id="managed_profile",
+            status="warn",
+            summary="Managed profile directory exists but appears to be in use.",
+            details=", ".join(str(path) for path in lock_paths),
+            next="close Browser CLI-owned Chrome windows or inspect browser-cli status",
+        )
+    return DoctorCheck(
+        id="managed_profile",
+        status="pass",
+        summary="Managed profile directory is writable.",
+        details=str(profile_root),
+    )
+
+
+def _daemon_check(app_paths: AppPaths) -> DoctorCheck:
+    run_info = read_run_info()
+    return _runtime_reachability_check(
+        id="daemon",
+        metadata_exists=run_info is not None,
+        reachable=probe_socket(),
+        metadata_path=app_paths.run_info_path,
+        reachable_summary="Browser daemon is reachable.",
+        unreachable_summary="Daemon runtime metadata exists but the daemon is not reachable.",
+        missing_summary="Daemon is not running yet.",
+        reachable_details=app_paths.socket_path,
+        unreachable_next="run browser-cli reload",
+        missing_next="run browser-cli read https://example.com or browser-cli status when you are ready",
+    )
+
+
+def _automation_service_check(app_paths: AppPaths) -> DoctorCheck:
+    run_info = read_automation_service_run_info()
+    return _runtime_reachability_check(
+        id="automation_service",
+        metadata_exists=run_info is not None,
+        reachable=_probe_automation_service(run_info),
+        metadata_path=app_paths.automation_service_run_info_path,
+        reachable_summary="Automation service is reachable.",
+        unreachable_summary="Automation service metadata exists but service is not reachable.",
+        missing_summary="Automation service is not running yet.",
+        reachable_details=app_paths.automation_service_run_info_path,
+        unreachable_next="run browser-cli automation status or browser-cli automation ui after restarting the service",
+        missing_next="run browser-cli automation status or browser-cli automation ui when you need published automation management",
+    )
+
+
+def _extension_check(daemon_payload: dict[str, Any] | None) -> DoctorCheck:
+    if daemon_payload is None:
+        return DoctorCheck(
+            id="extension",
+            status="warn",
+            summary="Extension reachability is unavailable until the daemon is running.",
+            next="run browser-cli status after the daemon starts if you need extension mode",
+        )
+    extension = dict(daemon_payload.get("extension") or {})
+    if bool(extension.get("connected")) and bool(extension.get("capability_complete")):
+        return DoctorCheck(
+            id="extension",
+            status="pass",
+            summary="Browser CLI extension is connected and capability-complete.",
+        )
+    if bool(extension.get("connected")):
+        missing = ", ".join(str(item) for item in (extension.get("missing_capabilities") or []))
+        details = missing or "required capability set is incomplete"
+        return DoctorCheck(
+            id="extension",
+            status="warn",
+            summary="Browser CLI extension is connected but incomplete.",
+            details=details,
+            next="reload the extension or run browser-cli reload after reconnecting it",
+        )
+    return DoctorCheck(
+        id="extension",
+        status="warn",
+        summary="Browser CLI extension is not connected.",
+        next="start with managed profile mode, or connect the extension if you need real Chrome behavior",
+    )
+
+
+def _discover_chrome_executable() -> Path:
+    if sys.platform == "darwin":
+        candidates = [Path("/Applications/Google Chrome.app/Contents/MacOS/Google Chrome")]
+    elif sys.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 RuntimeError(f"Unsupported platform for Chrome discovery: {sys.platform}")
+
+    for candidate in candidates:
+        if candidate.exists():
+            return candidate
+    raise RuntimeError("Stable Google Chrome was not found on this machine.")
+
+
+def _daemon_runtime_payload() -> dict[str, Any] | None:
+    run_info = read_run_info()
+    if not probe_socket() or not run_info_is_compatible(run_info):
+        return None
+    try:
+        response = send_command("runtime-status", {"warmup": False}, start_if_needed=False)
+    except Exception:
+        return None
+    data = response.get("data")
+    return dict(data) if isinstance(data, dict) else None
+
+
+def _is_writable_directory(path: Path) -> bool:
+    return path.is_dir() and os.access(path, os.W_OK)
+
+
+def _runtime_reachability_check(
+    *,
+    id: str,
+    metadata_exists: bool,
+    reachable: bool,
+    metadata_path: Path,
+    reachable_summary: str,
+    unreachable_summary: str,
+    missing_summary: str,
+    reachable_details: Path,
+    unreachable_next: str,
+    missing_next: str,
+) -> DoctorCheck:
+    if reachable:
+        return DoctorCheck(
+            id=id,
+            status="pass",
+            summary=reachable_summary,
+            details=str(reachable_details),
+        )
+    if metadata_exists:
+        return DoctorCheck(
+            id=id,
+            status="warn",
+            summary=unreachable_summary,
+            details=str(metadata_path),
+            next=unreachable_next,
+        )
+    return DoctorCheck(
+        id=id,
+        status="warn",
+        summary=missing_summary,
+        next=missing_next,
+    )

browser_cli/commands/install_skills.py

@@ -0,0 +1,138 @@
+"""Install packaged Browser CLI skills into a target skills directory."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import shutil
+import uuid
+from dataclasses import dataclass
+from importlib import resources
+from importlib.abc import Traversable
+from pathlib import Path
+
+from browser_cli.errors import InvalidInputError, OperationFailedError
+
+PUBLIC_SKILL_NAMES = (
+    "browser-cli-converge",
+    "browser-cli-delivery",
+    "browser-cli-explore",
+)
+
+
+@dataclass(frozen=True, slots=True)
+class PackagedSkill:
+    name: str
+    source: Traversable | Path
+
+
+def _packaged_skills_root() -> Traversable:
+    return resources.files("browser_cli.packaged_skills")
+
+
+def discover_packaged_skills() -> list[PackagedSkill]:
+    root = _packaged_skills_root()
+    discovered: list[PackagedSkill] = []
+    for name in PUBLIC_SKILL_NAMES:
+        skill_root = root.joinpath(name)
+        if not skill_root.is_dir():
+            raise InvalidInputError(f"Packaged skill is missing from this build: {name}")
+        skill_doc = skill_root.joinpath("SKILL.md")
+        if not skill_doc.is_file():
+            raise InvalidInputError(
+                f"Packaged skill is incomplete in this build: {name} is missing SKILL.md"
+            )
+        discovered.append(PackagedSkill(name=name, source=skill_root))
+    return discovered
+
+
+def get_skills_target_path(target: str | None) -> Path:
+    if target:
+        return Path(target).expanduser().resolve()
+    return Path.home() / ".agents" / "skills"
+
+
+def install_skills_from_paths(
+    skills: list[PackagedSkill],
+    target: Path,
+    *,
+    dry_run: bool = False,
+) -> list[tuple[str, str]]:
+    results: list[tuple[str, str]] = []
+    if not dry_run:
+        try:
+            target.mkdir(parents=True, exist_ok=True)
+        except OSError as exc:
+            raise OperationFailedError(
+                f"Could not create skills target directory {target}: {exc}"
+            ) from exc
+    for skill in skills:
+        destination = target / skill.name
+        exists = destination.exists()
+        status = (
+            "would update"
+            if dry_run and exists
+            else "would install"
+            if dry_run
+            else "updated"
+            if exists
+            else "installed"
+        )
+        if not dry_run:
+            _install_one_skill(skill, destination)
+        results.append((skill.name, status))
+    return results
+
+
+def _install_one_skill(skill: PackagedSkill, destination: Path) -> None:
+    source = skill.source if isinstance(skill.source, Traversable) else Path(skill.source)
+    staged = destination.with_name(f"{destination.name}.tmp-{uuid.uuid4().hex}")
+    try:
+        _copy_skill_tree(source, staged)
+        backup = _swap_staged_directory(staged, destination)
+        if backup is not None:
+            shutil.rmtree(backup, ignore_errors=True)
+    except OSError as exc:
+        if staged.exists():
+            shutil.rmtree(staged, ignore_errors=True)
+        raise OperationFailedError(
+            f"Could not install skill {skill.name} to {destination}: {exc}"
+        ) from exc
+
+
+def _copy_skill_tree(source: Traversable | Path, destination: Path) -> None:
+    destination.mkdir(parents=True, exist_ok=False)
+    for child in source.iterdir():
+        child_destination = destination / child.name
+        if child.is_dir():
+            _copy_skill_tree(child, child_destination)
+            continue
+        with child.open("rb") as handle, child_destination.open("wb") as output:
+            shutil.copyfileobj(handle, output)
+
+
+def _swap_staged_directory(staged: Path, destination: Path) -> Path | None:
+    backup: Path | None = None
+    if destination.exists():
+        backup = destination.with_name(f"{destination.name}.bak-{uuid.uuid4().hex}")
+        os.replace(destination, backup)
+    try:
+        os.replace(staged, destination)
+    except OSError:
+        if backup is not None and backup.exists() and not destination.exists():
+            os.replace(backup, destination)
+        raise
+    return backup
+
+
+def run_install_skills_command(args: argparse.Namespace) -> str:
+    skills = discover_packaged_skills()
+    target = get_skills_target_path(getattr(args, "target", None))
+    results = install_skills_from_paths(skills, target, dry_run=bool(args.dry_run))
+    mode = "(dry-run) " if args.dry_run else ""
+    lines = [f"{mode}Installing skills to {target}:", ""]
+    for skill_name, status in results:
+        lines.append(f"  {skill_name}: {status}")
+    lines.append("")
+    lines.append(f"Total: {len(results)} skill(s)")
+    return "\n".join(lines) + "\n"

browser_cli/commands/paths.py

@@ -0,0 +1,31 @@
+"""Filesystem path discovery command."""
+
+from __future__ import annotations
+
+from argparse import Namespace
+
+from browser_cli.constants import get_app_paths
+from browser_cli.outputs.json import render_json_payload
+
+
+def _paths_payload() -> dict[str, str]:
+    app_paths = get_app_paths()
+    return {
+        "home": str(app_paths.home),
+        "tasks_dir": str(app_paths.tasks_dir),
+        "automations_dir": str(app_paths.automations_dir),
+        "artifacts_dir": str(app_paths.artifacts_dir),
+        "daemon_log_path": str(app_paths.daemon_log_path),
+        "automation_db_path": str(app_paths.automation_db_path),
+        "automation_service_run_info_path": str(app_paths.automation_service_run_info_path),
+        "automation_service_log_path": str(app_paths.automation_service_log_path),
+    }
+
+
+def run_paths_command(args: Namespace) -> str:
+    payload = _paths_payload()
+    if getattr(args, "json", False):
+        return render_json_payload({"ok": True, "data": payload, "meta": {"action": "paths"}})
+    lines = ["Paths", ""]
+    lines.extend(f"{key}: {value}" for key, value in payload.items())
+    return "\n".join(lines) + "\n"

browser_cli/commands/read.py

@@ -0,0 +1,33 @@
+"""Read command handler."""
+
+from __future__ import annotations
+
+import sys
+from argparse import Namespace
+
+from browser_cli.outputs.render import render_output
+from browser_cli.task_runtime import BrowserCliTaskClient
+
+
+def normalize_url(url: str) -> str:
+    if "://" in url:
+        return url
+    return f"https://{url}"
+
+
+def run_read_command(args: Namespace) -> str:
+    client = BrowserCliTaskClient()
+    result = client.read(
+        normalize_url(args.url),
+        output_mode="snapshot" if args.snapshot else "html",
+        scroll_bottom=bool(args.scroll_bottom),
+    )
+    if result.used_fallback_profile and result.fallback_profile_dir:
+        message = (
+            "Info: primary Chrome profile unavailable; using fallback profile at "
+            f"{result.fallback_profile_dir}"
+        )
+        if result.fallback_reason:
+            message += f". Reason: {result.fallback_reason}"
+        sys.stderr.write(message + "\n")
+    return render_output(result.body)

browser_cli/commands/reload.py

@@ -0,0 +1,51 @@
+"""Lifecycle reload command."""
+
+from __future__ import annotations
+
+from argparse import Namespace
+
+from browser_cli.daemon.client import (
+    cleanup_runtime,
+    ensure_daemon_running,
+    send_command,
+    wait_for_daemon_stop,
+)
+from browser_cli.errors import BrowserCliError, OperationFailedError
+
+from .status import collect_status_report, render_status_report
+
+
+def run_reload_command(_args: Namespace) -> str:
+    graceful_stop = False
+    forced_cleanup = False
+
+    try:
+        stop_response = send_command("stop", start_if_needed=False)
+        graceful_stop = not bool((stop_response.get("data") or {}).get("already_stopped"))
+    except BrowserCliError:
+        graceful_stop = False
+
+    if not wait_for_daemon_stop():
+        forced_cleanup = True
+
+    if cleanup_runtime(fast_kill=True):
+        forced_cleanup = True
+
+    try:
+        ensure_daemon_running()
+        after = collect_status_report(warmup=False)
+    except BrowserCliError as exc:
+        raise OperationFailedError(
+            "Reload cleared Browser CLI runtime state, but restart failed. "
+            f"Reason: {exc}. Run `browser-cli status` and inspect the daemon log for details."
+        ) from exc
+
+    lines = [
+        "Reload: complete",
+        f"- graceful stop: {'yes' if graceful_stop else 'no'}",
+        f"- forced cleanup: {'yes' if forced_cleanup else 'no'}",
+        f"- result: {after.overall_status}",
+        "",
+        render_status_report(after).rstrip(),
+    ]
+    return "\n".join(lines) + "\n"