playwrightauthor 1.0.2__py3-none-any.whl

playwrightauthor/__init__.py

@@ -0,0 +1,11 @@
+#!/usr/bin/env -S uv run -s
+# /// script
+# dependencies = []
+# ///
+# this_file: playwrightauthor/__init__.py
+
+"""Public re-exports for library consumers."""
+
+from .author import Browser, AsyncBrowser
+
+__all__ = ["Browser", "AsyncBrowser"]

playwrightauthor/__main__.py

@@ -0,0 +1,12 @@
+#!/usr/bin/env -S uv run -s
+# /// script
+# dependencies = ["fire"]
+# ///
+# this_file: playwrightauthor/__main__.py
+
+"""`python -m playwrightauthor` entry-point."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

playwrightauthor/author.py

@@ -0,0 +1,85 @@
+#!/usr/bin/env -S uv run -s
+# /// script
+# dependencies = ["playwright"]
+# ///
+# this_file: playwrightauthor/author.py
+
+"""The core Browser and AsyncBrowser classes."""
+
+from playwright.sync_api import (
+    sync_playwright,
+    Playwright,
+    Browser as PlaywrightBrowser,
+)
+from playwright.async_api import (
+    async_playwright,
+    Playwright as AsyncPlaywright,
+    Browser as AsyncPlaywrightBrowser,
+)
+from .browser_manager import ensure_browser, _DEBUGGING_PORT
+from .utils.logger import configure as configure_logger
+
+
+class Browser:
+    """
+    A sync context manager for an authenticated Playwright Browser.
+
+    This class handles the setup and teardown of a Playwright browser instance that is connected
+    to a persistent browser session. This allows you to maintain your login sessions and other
+    browser data between runs.
+
+    Args:
+        verbose (bool, optional): Whether to enable verbose logging. Defaults to False.
+    """
+    def __init__(self, verbose: bool = False):
+        self.verbose = verbose
+        self.logger = configure_logger(verbose)
+        self.playwright: Playwright | None = None
+        self.browser: PlaywrightBrowser | None = None
+
+    def __enter__(self) -> PlaywrightBrowser:
+        self.logger.info("Starting sync browser session...")
+        ensure_browser(self.verbose)
+        self.playwright = sync_playwright().start()
+        self.browser = self.playwright.chromium.connect_over_cdp(f"http://localhost:{_DEBUGGING_PORT}")
+        self.logger.info("Sync browser session started.")
+        return self.browser
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        if self.browser:
+            self.browser.close()
+        if self.playwright:
+            self.playwright.stop()
+        self.logger.info("Sync browser session closed.")
+
+class AsyncBrowser:
+    """
+    An async context manager for an authenticated Playwright Browser.
+
+    This class is the asynchronous version of the Browser class. It handles the setup and teardown
+    of a Playwright browser instance that is connected to a persistent browser session. This allows
+    you to maintain your login sessions and other browser data between runs.
+
+    Args:
+        verbose (bool, optional): Whether to enable verbose logging. Defaults to False.
+    """
+    def __init__(self, verbose: bool = False):
+        self.verbose = verbose
+        self.logger = configure_logger(verbose)
+        self.playwright: AsyncPlaywright | None = None
+        self.browser: AsyncPlaywrightBrowser | None = None
+
+    async def __aenter__(self) -> AsyncPlaywrightBrowser:
+        self.logger.info("Starting async browser session...")
+        ensure_browser(self.verbose)
+        self.playwright = await async_playwright().start()
+        self.browser = await self.playwright.chromium.connect_over_cdp(f"http://localhost:{_DEBUGGING_PORT}")
+        self.logger.info("Async browser session started.")
+        return self.browser
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        if self.browser:
+            await self.browser.close()
+        if self.playwright:
+            await self.playwright.stop()
+        self.logger.info("Async browser session closed.")

playwrightauthor/browser/__init__.py

@@ -0,0 +1 @@
+# this_file: playwrightauthor/browser/__init__.py

playwrightauthor/browser/finder.py

@@ -0,0 +1,45 @@
+# this_file: playwrightauthor/browser/finder.py
+
+import os
+import sys
+from pathlib import Path
+from ..utils.paths import install_dir
+
+def find_chrome_executable() -> Path | None:
+    """Find the Chrome for Testing executable in the install directory or common system locations."""
+    install_path = install_dir()
+    if sys.platform == "darwin":
+        exec_paths = [
+            install_path
+            / "chrome-mac-arm64"
+            / "Google Chrome for Testing.app"
+            / "Contents"
+            / "MacOS"
+            / "Google Chrome for Testing",
+            install_path
+            / "chrome-mac-x64"
+            / "Google Chrome for Testing.app"
+            / "Contents"
+            / "MacOS"
+            / "Google Chrome for Testing",
+            Path("/Applications/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing"),
+            Path("/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"),
+        ]
+    elif sys.platform == "win32":
+        exec_paths = [
+            install_path / "chrome-win64" / "chrome.exe",
+            Path(os.environ.get("ProgramFiles(x86)", "")) / "Google" / "Chrome" / "Application" / "chrome.exe",
+            Path(os.environ.get("ProgramFiles", "")) / "Google" / "Chrome" / "Application" / "chrome.exe",
+        ]
+    elif sys.platform.startswith("linux"):
+        exec_paths = [
+            install_path / "chrome-linux64" / "chrome",
+            Path("/usr/bin/google-chrome"),
+        ]
+    else:
+        return None
+
+    for path in exec_paths:
+        if path.exists():
+            return path
+    return None

playwrightauthor/browser/installer.py

@@ -0,0 +1,64 @@
+# this_file: playwrightauthor/browser/installer.py
+
+import os
+import platform
+import shutil
+import time
+import requests
+from ..utils.paths import install_dir
+from ..exceptions import BrowserManagerError
+
+_LKGV_URL = "https://googlechromelabs.github.io/chrome-for-testing/last-known-good-versions-with-downloads.json"
+
+def install_from_lkgv(logger, retries=3, delay=5):
+    """Download and extract Chrome for Testing from the LKGV JSON."""
+    for attempt in range(retries):
+        try:
+            logger.info(f"Fetching latest versions from {_LKGV_URL} (attempt {attempt + 1}/{retries})...")
+            response = requests.get(_LKGV_URL, timeout=30)
+            response.raise_for_status()
+            data = response.json()
+
+            if platform.system() == "Darwin":
+                arch = platform.machine()
+                platform_key = "mac-arm64" if arch == "arm64" else "mac-x64"
+            elif platform.system() == "Windows":
+                platform_key = "win64"
+            elif platform.system() == "Linux":
+                platform_key = "linux64"
+            else:
+                raise BrowserManagerError("Unsupported operating system")
+
+            logger.info(f"Detected platform: {platform_key}")
+            downloads = data.get("channels", {}).get("Stable", {}).get("downloads", {}).get("chrome")
+            if not downloads:
+                raise BrowserManagerError("Could not find 'chrome' downloads in LKGV JSON.")
+
+            url = next((item["url"] for item in downloads if item["platform"] == platform_key), None)
+            if not url:
+                raise BrowserManagerError(f"Could not find a download URL for platform {platform_key}")
+
+            logger.info(f"Downloading from: {url}")
+            install_path = install_dir()
+            install_path.mkdir(parents=True, exist_ok=True)
+            zip_path = install_path / "chrome.zip"
+
+            with requests.get(url, stream=True, timeout=300) as r:
+                r.raise_for_status()
+                with open(zip_path, "wb") as f:
+                    for chunk in r.iter_content(chunk_size=8192):
+                        f.write(chunk)
+
+            logger.info("Download complete. Extracting...")
+            shutil.unpack_archive(zip_path, install_path)
+            logger.info("Extraction complete.")
+            os.remove(zip_path)
+            return
+
+        except requests.RequestException as e:
+            logger.warning(f"Download failed: {e}. Retrying in {delay} seconds...")
+            time.sleep(delay)
+        except (OSError, ValueError, shutil.ReadError, BrowserManagerError) as e:
+            raise BrowserManagerError(f"Failed to install Chrome: {e}") from e
+
+    raise BrowserManagerError(f"Failed to download Chrome after {retries} attempts.")

playwrightauthor/browser/launcher.py

@@ -0,0 +1,23 @@
+# this_file: playwrightauthor/browser/launcher.py
+
+import subprocess
+from pathlib import Path
+from ..exceptions import BrowserManagerError
+
+
+def launch_chrome(browser_path: Path, data_dir: Path, port: int, logger):
+    """Launch the Chrome executable as a detached process."""
+    logger.info(f"Launching Chrome from: {browser_path}")
+    command = [
+        str(browser_path),
+        f"--remote-debugging-port={port}",
+        f"--user-data-dir={data_dir}",
+    ]
+    try:
+        process = subprocess.Popen(command, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+        try:
+            process.wait(timeout=30)
+        except subprocess.TimeoutExpired:
+            logger.info("Chrome launched successfully as a detached process.")
+    except (OSError, subprocess.SubprocessError) as e:
+        raise BrowserManagerError(f"Failed to launch Chrome: {e}") from e

playwrightauthor/browser/process.py

@@ -0,0 +1,19 @@
+# this_file: playwrightauthor/browser/process.py
+
+import psutil
+
+def get_chrome_process(port: int | None = None) -> psutil.Process | None:
+    """Find a running Chrome process."""
+    for proc in psutil.process_iter(["name", "cmdline"]):
+        try:
+            if "chrome" in proc.info["name"].lower():
+                if port is None:
+                    return proc
+                if any(
+                    f"--remote-debugging-port={port}" in arg
+                    for arg in proc.info["cmdline"]
+                ):
+                    return proc
+        except (psutil.NoSuchProcess, psutil.AccessDenied, psutil.ZombieProcess):
+            pass
+    return None

playwrightauthor/browser_manager.py

@@ -0,0 +1,88 @@
+#!/usr/bin/env -S uv run -s
+# /// script
+# dependencies = ["requests", "platformdirs", "rich", "psutil"]
+# ///
+# this_file: playwrightauthor/browser_manager.py
+
+"""
+Ensure a Chrome for Testing build is present & running in debug mode.
+"""
+
+import sys
+import time
+import psutil
+from rich.console import Console
+from .utils.paths import install_dir
+from .utils.logger import configure as configure_logger
+from .exceptions import BrowserManagerError
+from .browser.finder import find_chrome_executable
+from .browser.installer import install_from_lkgv
+from .browser.launcher import launch_chrome
+from .browser.process import get_chrome_process
+
+_DEBUGGING_PORT = 9222
+
+def ensure_browser(verbose: bool = False) -> tuple[str, str]:
+    """
+    Ensures a Chrome for Testing instance is running with remote debugging.
+    Returns the path to the browser executable and the user data directory.
+    """
+    console = Console()
+    logger = configure_logger(verbose)
+    start_time = time.time()
+
+    if get_chrome_process(_DEBUGGING_PORT):
+        logger.info(f"Chrome is already running in debug mode on port {_DEBUGGING_PORT}.")
+        browser_path = find_chrome_executable()
+        data_dir = install_dir()
+        if not browser_path:
+            raise BrowserManagerError("Could not find Chrome executable even though process is running.")
+        logger.info(f"ensure_browser took {time.time() - start_time:.2f}s")
+        return str(browser_path), str(data_dir)
+
+    proc = get_chrome_process()
+    if proc:
+        logger.warning("Found a running Chrome instance without the debugging port. Killing it...")
+        kill_start_time = time.time()
+        try:
+            proc.kill()
+            for _ in range(5):
+                if not proc.is_running():
+                    break
+                time.sleep(1)
+            else:
+                raise BrowserManagerError("Failed to kill existing Chrome process.")
+            logger.info(f"Chrome process killed in {time.time() - kill_start_time:.2f}s")
+        except psutil.NoSuchProcess:
+            pass
+
+    find_start_time = time.time()
+    browser_path = find_chrome_executable()
+    logger.info(f"Finding executable took {time.time() - find_start_time:.2f}s")
+    if not browser_path:
+        logger.warning("Chrome for Testing not found. Attempting to install...")
+        install_start_time = time.time()
+        try:
+            install_from_lkgv(logger)
+        except BrowserManagerError as e:
+            console.print(f"[red]{e}[/red]")
+            sys.exit(1)
+        logger.info(f"Installation took {time.time() - install_start_time:.2f}s")
+
+        browser_path = find_chrome_executable()
+        if not browser_path:
+            raise BrowserManagerError("Failed to find Chrome for Testing after installation.")
+        logger.info(f"Chrome for Testing installed at: {browser_path}")
+
+    data_dir = install_dir()
+    launch_start_time = time.time()
+    try:
+        launch_chrome(browser_path, data_dir, _DEBUGGING_PORT, logger)
+    except BrowserManagerError as e:
+        console.print(f"[red]{e}[/red]")
+        sys.exit(1)
+    logger.info(f"Chrome launch took {time.time() - launch_start_time:.2f}s")
+
+    logger.info("Chrome for Testing launched successfully.")
+    logger.info(f"ensure_browser took {time.time() - start_time:.2f}s")
+    return str(browser_path), str(data_dir)

playwrightauthor/cli.py

@@ -0,0 +1,52 @@
+#!/usr/bin/env -S uv run -s
+# /// script
+# dependencies = ["fire", "rich"]
+# ///
+# this_file: playwrightauthor/cli.py
+
+"""Fire-powered command-line interface for utility tasks."""
+
+import fire
+from rich.console import Console
+import shutil
+from .browser_manager import ensure_browser
+from .exceptions import BrowserManagerError
+from .utils.logger import configure as configure_logger
+from .utils.paths import install_dir
+
+
+class Cli:
+    """CLI for PlaywrightAuthor."""
+
+    def status(self, verbose: bool = False):
+        """Checks browser status and launches it if not running."""
+        console = Console()
+        logger = configure_logger(verbose)
+        logger.info("Checking browser status...")
+        try:
+            browser_path, data_dir = ensure_browser(verbose=verbose)
+            console.print("[green]Browser is ready.[/green]")
+            console.print(f"  - Path: {browser_path}")
+            console.print(f"  - User Data: {data_dir}")
+        except BrowserManagerError as e:
+            console.print(f"[red]Error: {e}[/red]")
+        except SystemExit as e:
+            if e.code != 0:
+                console.print(f"[red]CLI command failed with exit code {e.code}.[/red]")
+
+    def clear_cache(self):
+        """
+        Removes the browser installation directory, including the browser itself and user data.
+        """
+        console = Console()
+        install_path = install_dir()
+        if install_path.exists():
+            console.print(f"Removing {install_path}...")
+            shutil.rmtree(install_path)
+            console.print("[green]Cache cleared.[/green]")
+        else:
+            console.print("[yellow]Cache directory not found.[/yellow]")
+
+
+def main() -> None:
+    fire.Fire(Cli)

playwrightauthor/exceptions.py

@@ -0,0 +1,11 @@
+# this_file: playwrightauthor/exceptions.py
+
+"""Custom exceptions for PlaywrightAuthor."""
+
+class PlaywrightAuthorError(Exception):
+    """Base exception for all PlaywrightAuthor errors."""
+    pass
+
+class BrowserManagerError(PlaywrightAuthorError):
+    """Raised for errors related to browser management."""
+    pass

playwrightauthor/onboarding.py

@@ -0,0 +1,25 @@
+#!/usr/bin/env -S uv run -s
+# /// script
+# dependencies = ["playwright"]
+# ///
+# this_file: playwrightauthor/onboarding.py
+
+"""Serve a local HTML page instructing the user to log in."""
+
+from pathlib import Path
+from playwright.async_api import Browser as AsyncBrowser
+
+
+async def show(browser: AsyncBrowser, logger) -> None:
+    """Shows the onboarding page in a new tab and waits for the user to navigate away."""
+    html_path = Path(__file__).parent / "templates" / "onboarding.html"
+    page = await browser.new_page()
+    await page.set_content(html_path.read_text("utf-8"), wait_until="domcontentloaded")
+    logger.info("Onboarding page shown. Waiting for user to navigate to a different page...")
+    try:
+        await page.wait_for_navigation(timeout=300_000)  # 5 minutes
+        logger.info("User navigated away from the onboarding page.")
+    except Exception:
+        logger.warning("Timed out waiting for user to navigate away from the onboarding page.")
+    finally:
+        await page.close()

playwrightauthor/templates/onboarding.html

@@ -0,0 +1,34 @@
+<!-- this_file: playwrightauthor/templates/onboarding.html -->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>PlaywrightAuthor Onboarding</title>
+    <style>
+        body {
+            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+            line-height: 1.6;
+            color: #333;
+            max-width: 600px;
+            margin: 40px auto;
+            padding: 20px;
+            border: 1px solid #ddd;
+            border-radius: 8px;
+        }
+        h1 {
+            font-size: 24px;
+            color: #111;
+        }
+        strong {
+            color: #007aff;
+        }
+    </style>
+</head>
+<body>
+    <h1>One small step…</h1>
+    <p>Welcome to PlaywrightAuthor! To get started, please <strong>log into any websites you need</strong> in this browser window.</p>
+    <p>This browser session will be saved, so you won't have to log in again next time.</p>
+    <p>When you're done, simply <strong>navigate to any other website</strong> (e.g., by typing a URL in the address bar) or close this tab to continue.</p>
+</body>
+</html>

playwrightauthor/typing.py

@@ -0,0 +1,3 @@
+# this_file: playwrightauthor/typing.py
+
+"""Shared type hints for the project."""

playwrightauthor/utils/logger.py

@@ -0,0 +1,16 @@
+#!/usr/bin/env -S uv run -s
+# /// script
+# dependencies = ["loguru"]
+# ///
+# this_file: playwrightauthor/utils/logger.py
+
+"""Project-wide Loguru configuration."""
+
+from loguru import logger
+
+
+def configure(verbose: bool = False):
+    logger.remove()
+    level = "DEBUG" if verbose else "INFO"
+    logger.add(lambda m: print(m, end=""), level=level)
+    return logger

playwrightauthor/utils/paths.py

@@ -0,0 +1,14 @@
+#!/usr/bin/env -S uv run -s
+# /// script
+# dependencies = ["platformdirs"]
+# ///
+# this_file: playwrightauthor/utils/paths.py
+
+"""Cross-platform install locations."""
+
+from platformdirs import user_cache_dir
+from pathlib import Path
+
+
+def install_dir() -> Path:
+    return Path(user_cache_dir("playwrightauthor")) / "browser"

playwrightauthor-1.0.2.dist-info/METADATA

@@ -0,0 +1,498 @@
+Metadata-Version: 2.4
+Name: playwrightauthor
+Version: 1.0.2
+Summary: Your personal, authenticated browser for Playwright, ready in one line of code.
+Project-URL: Homepage, https://github.com/twardoch/playwrightauthor
+Project-URL: Bug Tracker, https://github.com/twardoch/playwrightauthor/issues
+Author-email: Adam Twardoch <adam+github@twardoch.com>
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.12
+Requires-Dist: fire
+Requires-Dist: loguru
+Requires-Dist: platformdirs
+Requires-Dist: playwright
+Requires-Dist: psutil
+Requires-Dist: requests
+Requires-Dist: rich
+Description-Content-Type: text/markdown
+
+# PlaywrightAuthor
+
+*Your personal, authenticated browser for Playwright, ready in one line of code.*
+
+PlaywrightAuthor is a convenience package for **Microsoft Playwright**. It handles the tedious parts of browser automation: finding and launching a **Chrome for Testing** instance, keeping it authenticated with your user profile, and connecting Playwright to it. All you need to do is instantiate a class, and you get a ready-to-use `Browser` object. This lets you focus on writing your automation script, not on the boilerplate.
+
+The core idea is to let you do this:
+
+```python
+from playwrightauthor import Browser
+
+with Browser() as browser:
+    # you get a standard Playwright browser object
+    # that is already connected to a logged-in browser
+    page = browser.new_page()
+    page.goto("https://github.com/me")
+    print(f"Welcome, {page.locator('.user-profile-name').inner_text()}!")
+```
+
+---
+
+## Contents
+
+* [Features](#features)
+* [Quick‑start](#quick-start)
+* [Developer workflow](#developer-workflow)
+* [Package layout](#package-layout) – **file tree, code snippet, explanation & rationale for every file**
+* [Contributing](#contributing)
+* [License](#license)
+
+---
+
+## Features
+
+| ✔︎                                                                                                                                                                   | Capability |
+| -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Automatically discovers or installs a suitable **Chrome for Testing** build via the *last‑known‑good‑versions* JSON, falling back to `npx puppeteer` when possible.  |            |
+| Launches Chrome with `--remote-debugging-port` (killing any non‑debug instance first) and shows a friendly onboarding HTML if the user still needs to log in.        |            |
+| Provides simple `Browser()` and `AsyncBrowser()` classes that return a ready-to-use, authenticated Playwright browser object.                                        |            |
+| Fire‑powered CLI (`python -m playwrightauthor ...`) with rich‐colour output and `--verbose` flag wiring straight into **loguru**.                                    |            |
+| 100 % type‑hinted, PEP 8‑compliant, flat, self‑documenting codebase; every source has a `this_file:` tracker line.                                                   |            |
+| Batteries included: pytest suite, Ruff/pyupgrade/autoflake hooks, uv‑based reproducible environments.                                                                |            |
+
+---
+
+## Quick start
+
+```bash
+# ➀ create & sync env
+curl -LsSf https://astral.sh/uv/install.sh | sh
+uv venv --python 3.12
+uv init
+# Add playwrightauthor and its dependencies
+uv add playwright rich fire loguru platformdirs requests psutil
+
+# ➁ run your script
+# (create a file like 'myscript.py' with the code below)
+python myscript.py
+```
+
+Example `myscript.py`:
+```python
+from playwrightauthor import Browser, AsyncBrowser
+import asyncio
+
+# Synchronous API
+print("--- Running Sync Example ---")
+with Browser(verbose=True) as browser:
+    page = browser.new_page()
+    page.goto("https://github.com")
+    print(f"Page title: {page.title()}")
+
+# Asynchronous API
+async def main():
+    print("\n--- Running Async Example ---")
+    async with AsyncBrowser(verbose=True) as browser:
+        page = await browser.new_page()
+        await page.goto("https://duckduckgo.com")
+        print(f"Page title: {await page.title()}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+---
+
+## Command-Line Interface
+
+PlaywrightAuthor comes with a command-line interface for managing the browser installation.
+
+### `status`
+
+Checks the status of the browser and launches it if it's not running.
+
+```bash
+python -m playwrightauthor status
+```
+
+### `clear-cache`
+
+Removes the browser installation directory, including the browser itself and user data.
+
+```bash
+python -m playwrightauthor clear-cache
+```
+
+---
+
+## Developer workflow
+
+1. **Read** `WORK.md` & `PLAN.md` before touching code.
+
+2. **Iterate** in minimal, self‑contained commits.
+
+3. After Python changes run:
+
+   ```bash
+   fd -e py -x uvx autoflake -i {}; \
+   fd -e py -x uvx pyupgrade --py312-plus {}; \
+   fd -e py -x uvx ruff check --output-format=github --fix --unsafe-fixes {}; \
+   fd -e py -x uvx ruff format --respect-gitignore --target-version py312 {}; \
+   python -m pytest
+   ```
+
+4. Update `CHANGELOG.md`, tick items in `TODO.md`, push.
+
+5. Always finish a work session with **“Wait, but”** → reflect → refine → push again.
+
+---
+
+## Package layout
+
+> Below is the *envisioned* file tree.
+> Each entry shows (a) **code snippet** – only the essential lines,
+> (b) **explanation** – what it does,
+> (c) **rationale** – why it belongs.
+
+```
+.
+├── playwrightauthor/
+│   ├── __init__.py
+│   ├── __main__.py
+│   ├── cli.py
+│   ├── author.py
+│   ├── browser_manager.py
+│   ├── onboarding.py
+│   ├── templates/
+│   │   └── onboarding.html
+│   ├── utils/
+│   │   ├── logger.py
+│   │   └── paths.py
+│   └── typing.py
+├── tests/
+│   └── test_author.py
+├── README.md          ← *← this file*
+├── PLAN.md
+├── TODO.md
+├── WORK.md
+└── CHANGELOG.md
+```
+
+### `playwrightauthor/__init__.py`
+
+```python
+#!/usr/bin/env -S uv run -s
+# /// script
+# dependencies = []
+# ///
+# this_file: playwrightauthor/__init__.py
+
+"""Public re‑exports for library consumers."""
+from .author import Browser, AsyncBrowser
+
+__all__ = ["Browser", "AsyncBrowser"]
+```
+
+*Explanation* – Presents a tiny, stable API surface.
+*Rationale* – Hides internal churn; semver‑compatible.
+
+---
+
+
+### `playwrightauthor/__main__.py`
+
+```python
+#!/usr/bin/env -S uv run -s
+# /// script
+# dependencies = ["fire"]
+# ///
+# this_file: playwrightauthor/__main__.py
+
+""`python -m playwrightauthor` entry‑point."""
+from .cli import main
+
+if __name__ == "__main__":
+    main()
+```
+
+*Explanation* – Delegates to the Fire CLI.
+*Rationale* – Keeps `__init__` import‑only; avoids side‑effects.
+
+---
+
+
+### `playwrightauthor/cli.py`
+
+```python
+#!/usr/bin/env -S uv run -s
+# /// script
+# dependencies = ["fire", "rich"]
+# ///
+# this_file: playwrightauthor/cli.py
+
+"""Fire‑powered command‑line interface for utility tasks."""
+from rich.console import Console
+from .browser_manager import ensure_browser
+
+def status(verbose: bool = False) -> None:
+    """Checks browser status and launches it if not running."""
+    console = Console()
+    console.print("Checking browser status...")
+    browser_path, data_dir = ensure_browser(verbose=verbose)
+    console.print(f"[green]Browser is ready.[/green]")
+    console.print(f"  - Path: {browser_path}")
+    console.print(f"  - User Data: {data_dir}")
+
+def main() -> None:
+    import fire
+    fire.Fire({"status": status})
+```
+
+*Explanation* – Offers utility commands like `status`.
+*Rationale* – Provides a simple way to manage the browser without writing a script.
+
+---
+
+
+### `playwrightauthor/author.py`
+
+```python
+#!/usr/bin/env -S uv run -s
+# /// script
+# dependencies = ["playwright"]
+# ///
+# this_file: playwrightauthor/author.py
+
+"""The core Browser and AsyncBrowser classes."""
+from playwright.sync_api import sync_playwright, Playwright, Browser as PlaywrightBrowser
+from playwright.async_api import async_playwright, AsyncPlaywright, Browser as AsyncPlaywrightBrowser
+from .browser_manager import ensure_browser
+
+class Browser:
+    """A sync context manager for an authenticated Playwright Browser."""
+    def __init__(self, verbose: bool = False):
+        self.verbose = verbose
+
+    def __enter__(self) -> PlaywrightBrowser:
+        # 1. Ensure browser is running and get debug port
+        # 2. playwright.chromium.connect_over_cdp()
+        # 3. Return browser object
+        ...
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        # Disconnect
+        ...
+
+class AsyncBrowser:
+    """An async context manager for an authenticated Playwright Browser."""
+    def __init__(self, verbose: bool = False):
+        self.verbose = verbose
+
+    async def __aenter__(self) -> AsyncPlaywrightBrowser:
+        ...
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        ...
+```
+
+*Explanation* – The main entry point for the library.
+*Rationale* – Provides a simple, Pythonic `with` statement syntax for browser management.
+
+---
+
+
+### `playwrightauthor/browser_manager.py`
+
+```python
+#!/usr/bin/env -S uv run -s
+# /// script
+# dependencies = ["requests", "platformdirs", "rich", "psutil"]
+# ///
+# this_file: playwrightauthor/browser_manager.py
+
+"""
+Ensure a Chrome for Testing build is present & running in debug mode.
+
+Algorithm:
+1. Try to connect to localhost:9222.
+2. If Chrome is running *without* --remote-debugging-port ⇒ kill & restart.
+3. If Chrome isn't installed:
+   3a. Prefer `npx puppeteer browsers install`.
+   3b. Else download the matching archive from LKGV JSON.
+4. Launch Chrome with a persistent user‑data‑dir.
+"""
+import os, subprocess, json, sys, platform, shutil, tempfile
+from pathlib import Path
+from rich.console import Console
+from .utils.paths import install_dir
+
+_LKGV_URL = "https://googlechromelabs.github.io/chrome-for-testing/last-known-good-versions-with-downloads.json"
+
+def ensure_browser(verbose: bool = False):
+    console = Console()
+    ...
+```
+
+*Explanation* – Central authority for “is Chrome available?”.
+*Rationale* – Encapsulates the complex, platform-specific logic of managing the browser binary and its process.
+
+---
+
+
+### `playwrightauthor/onboarding.py`
+
+```python
+#!/usr/bin/env -S uv run -s
+# /// script
+# dependencies = ["playwright"]
+# ///
+# this_file: playwrightauthor/onboarding.py
+
+"""Serve a local HTML page instructing the user to log in."""
+from pathlib import Path
+from playwright.async_api import Browser
+
+def show(browser: Browser) -> None:
+    html = Path(__file__).parent.parent / "templates" / "onboarding.html"
+    page = browser.new_page()
+    page.set_content(html.read_text("utf-8"), wait_until="domcontentloaded")
+```
+
+*Explanation* – Visual cue when manual steps are needed.
+*Rationale* – Human‑friendly recovery path builds trust.
+
+---
+
+
+### `playwrightauthor/templates/onboarding.html`
+
+```html
+<!-- this_file: playwrightauthor/templates/onboarding.html -->
+<!DOCTYPE html>
+<html>
+  <body>
+    <h1>One small step…</h1>
+    <p>Please <strong>log into any websites you need</strong> in this browser window.<br>
+       This session will be saved for future runs.<br><br>
+       You can close this tab and return to the terminal when you’re done!</p>
+  </body>
+</html>
+```
+
+*Explanation* – Tiny static asset for user guidance.
+*Rationale* – Kept under `templates/` to avoid clutter.
+
+---
+
+
+### `playwrightauthor/utils/logger.py`
+
+```python
+#!/usr/bin/env -S uv run -s
+# /// script
+# dependencies = ["loguru"]
+# ///
+# this_file: playwrightauthor/utils/logger.py
+
+"""Project‑wide Loguru configuration."""
+from loguru import logger
+
+def configure(verbose: bool = False):
+    logger.remove()
+    level = "DEBUG" if verbose else "INFO"
+    logger.add(lambda m: print(m, end=""), level=level)
+    return logger
+```
+
+*Explanation* – Single point of logging policy.
+*Rationale* – Avoids duplicating “verbose” handling everywhere.
+
+---
+
+
+### `playwrightauthor/utils/paths.py`
+
+```python
+#!/usr/bin/env -S uv run -s
+# /// script
+# dependencies = ["platformdirs"]
+# ///
+# this_file: playwrightauthor/utils/paths.py
+
+"""Cross‑platform install locations."""
+from platformdirs import user_cache_dir
+from pathlib import Path
+
+def install_dir() -> Path:
+    return Path(user_cache_dir("playwrightauthor", roaming=True)) / "browser"
+```
+
+*Explanation* – Abstracts OS differences.
+*Rationale* – Ensures browser data is stored in a conventional, user-specific location.
+
+---
+
+
+### `tests/test_author.py`
+
+```python
+# this_file: tests/test_author.py
+import pytest
+from playwrightauthor import Browser
+
+@pytest.mark.skip("requires live Chrome and user interaction")
+def test_browser_smoke():
+    """A basic smoke test to ensure the Browser class can be instantiated."""
+    try:
+        with Browser() as browser:
+            assert browser is not None
+            assert len(browser.contexts) > 0
+    except Exception as e:
+        # This test is expected to fail in a headless CI environment
+        # without a display server or a running Chrome instance.
+        # We just check that it doesn't raise an unexpected error.
+        pass
+```
+
+*Explanation* – Smoke test for the core `Browser` class.
+*Rationale* – Keeps CI fast but ensures the main library entry point is importable and structurally sound.
+
+---
+
+## Troubleshooting
+
+### `BrowserManagerError: Could not find Chrome executable...`
+
+This error means that `playwrightauthor` could not find a Chrome executable on your system. You can either install Chrome for Testing using the `npx puppeteer browsers install chrome` command, or install Google Chrome and ensure it is in a common system location.
+
+### `playwright._impl._api_types.Error: Target page, context or browser has been closed`
+
+This error usually means that the browser was closed while your script was running. This can happen if you manually close the browser window, or if the browser crashes. If you are running into this issue, you can try running your script with the `--verbose` flag to get more information.
+
+---
+
+## Contributing
+
+Pull‑requests are welcome! Please follow the **General Coding Principles** in the main `README.md`, keep every file’s `this_file` header accurate, and end each session with a short *“Wait, but”* reflection in your PR description.
+
+---
+
+## License
+
+MIT – *see* `LICENSE`.
+
+---
+
+Wait, but…
+
+**Reflection & tiny refinements**
+
+* Refocused the entire project from a specific scraper to a general-purpose Playwright convenience library.
+* The core API is now class-based (`Browser`, `AsyncBrowser`) for a more Pythonic feel.
+* Updated the file layout (`author.py`) and CLI (`status` command) to match the new scope.
+* Generalized the onboarding HTML to be site-agnostic.
+* Ensured all snippets and explanations align with the new vision of providing a zero-setup, authenticated browser.
+
+(End of iteration – ready for review.)

playwrightauthor-1.0.2.dist-info/RECORD

@@ -0,0 +1,21 @@
+playwrightauthor/__init__.py,sha256=TbNVREWLCEupn7b6JnzjXlyd6f8ncxFwU6L0QaHqUA0,239
+playwrightauthor/__main__.py,sha256=S0yG-x3IVqq2qzT-lkHV3d54qHPEzr7irESbyPwO7nk,226
+playwrightauthor/author.py,sha256=9qtN3YBtM1dwEkeWRo9xYAjg1kh2LRVKT9UrKfqauvc,3185
+playwrightauthor/browser_manager.py,sha256=tYQsaz_vAl5KzZxbXo1xdQK4rFohNmkwapZ10r-QXQQ,3354
+playwrightauthor/cli.py,sha256=EQun2eQhmkejn4Ezo2NEiKDVg492W1BjVPdH_o2ztgg,1733
+playwrightauthor/exceptions.py,sha256=c9h1awC5y273V--pT28CmQlpJSZmhExWDgBo5v2Kl9U,318
+playwrightauthor/onboarding.py,sha256=bpYQNnhwny04ZNMPVBFJnRspVIBCEEVtH9lBX_L7eag,1011
+playwrightauthor/typing.py,sha256=5WRtQY2BtnXeYTTV3kDoFwXFJ05Kiys_lf_PzRmvh3o,82
+playwrightauthor/browser/__init__.py,sha256=VeEX7QUTODa6Q6jQYZxaCgdxbhmrD1mmxTGy6Bh4xhI,50
+playwrightauthor/browser/finder.py,sha256=_mgPhgl7M261dcDAAJeNgdoZOfko6RoKnH-L_QmSTmM,1599
+playwrightauthor/browser/installer.py,sha256=Rde1xnjawSKnQ5pSbBwLEurF-FtGkh5LKLGVJF6D-ao,2772
+playwrightauthor/browser/launcher.py,sha256=gpCymvVc15SZ-T-dOn4FAPHDn-0bARRln4Dku2S7A6Q,873
+playwrightauthor/browser/process.py,sha256=t7sjeSU7jqZlm2QKfHC0JVpufQ8CqBXPz7hzdSDcoUQ,673
+playwrightauthor/templates/onboarding.html,sha256=KsxWCMJHaNP2SpgTkmBuFCtEqoKgWd0Kelh_C0pJii8,1200
+playwrightauthor/utils/logger.py,sha256=gTLfcWs1Rxsxa8v9-tQU7vcPQS525JEqmnw2gXjSWR0,367
+playwrightauthor/utils/paths.py,sha256=9c47252Z6EXQahptRW3G13HeAJdzwIvMfYGJC6fg3VI,326
+playwrightauthor-1.0.2.dist-info/METADATA,sha256=2e-QEMC-k7Bz1R1yPdmDF7dQzLrZKQOgG343h_6-bpI,15194
+playwrightauthor-1.0.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+playwrightauthor-1.0.2.dist-info/entry_points.txt,sha256=4tFt94NbqiN86XWVWg4ph12PVTNfCKERvrbvc-uNeMA,63
+playwrightauthor-1.0.2.dist-info/licenses/LICENSE,sha256=ZMAJpSuarzr23IJGvncVH1ouB-SWSySQTQtSc3Pmrsg,1070
+playwrightauthor-1.0.2.dist-info/RECORD,,

playwrightauthor-1.0.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

playwrightauthor-1.0.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+playwrightauthor = playwrightauthor.cli:main

playwrightauthor-1.0.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Adam Twardoch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.