ai-dev-browser 0.6.0__tar.gz → 0.6.2__tar.gz

{ai_dev_browser-0.6.0 → ai_dev_browser-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ai-dev-browser
-Version: 0.6.0
+Version: 0.6.2
 Summary: A browser for AI to develop web automation — human-like automation that works seamlessly in a world designed for humans
 Author: sudoprivacy
 License: AGPL-3.0

{ai_dev_browser-0.6.0 → ai_dev_browser-0.6.2}/ai_dev_browser/__init__.py

@@ -99,6 +99,7 @@ __all__ = [
     "browser_start",
     "browser_stop",
     "connect_browser",
+    "quick_connect",
 ]
 
 # Vendored CDP protocol module
@@ -107,4 +108,4 @@ from . import cdp
 from .core import connect_browser
 
 # Core functions also available at package level
-from .core import browser_start, browser_stop
+from .core import browser_start, browser_stop, quick_connect

{ai_dev_browser-0.6.0 → ai_dev_browser-0.6.2}/ai_dev_browser/core/__init__.py

@@ -53,7 +53,12 @@ from .config import (
 )
 
 # Connection
-from .connection import connect_browser, get_active_tab, graceful_close_browser
+from .connection import (
+    connect_browser,
+    get_active_tab,
+    graceful_close_browser,
+    quick_connect,
+)
 
 # Cookies
 from .cookies import cookies_list, cookies_load, cookies_save
@@ -168,6 +173,7 @@ __all__ = [
     "connect_browser",
     "get_active_tab",
     "graceful_close_browser",
+    "quick_connect",
     # Navigation
     "page_goto",
     "page_reload",

{ai_dev_browser-0.6.0 → ai_dev_browser-0.6.2}/ai_dev_browser/core/browser.py

@@ -76,7 +76,17 @@ def browser_start(
     reuse: ReuseStrategy = DEFAULT_REUSE_STRATEGY,
     startup_timeout: float = 30.0,
 ) -> dict:
-    """Start or reuse a browser instance.
+    """Use when: you're an orchestrator that needs explicit Chrome
+    lifecycle control — managing port assignments, profile-specific
+    reuse, knowing the exact PID, calling `browser_stop` later.
+    Returns `{port, pid, headless, url, profile, reused, message}`.
+
+    For ad-hoc Python scripts (`python -c "..."`, a one-off
+    `script.py`) that just want a Tab to act on without writing the
+    full `browser_start → connect_browser → get_active_tab` ceremony,
+    prefer `from ai_dev_browser import quick_connect` — auto-detects
+    a running browser (env var → workspace scan), starts one if
+    needed, and yields a context-managed Tab in one line.
 
     Args:
         port: Debug port (auto-assigned if None)

{ai_dev_browser-0.6.0 → ai_dev_browser-0.6.2}/ai_dev_browser/core/connection.py

@@ -1,17 +1,22 @@
 """Browser connection utilities.
 
-Provides BrowserClient (CDP client), CookieJar, connect_browser, get_active_tab.
+Provides BrowserClient (CDP client), CookieJar, connect_browser,
+get_active_tab, and quick_connect (one-line setup for ad-hoc Python
+scripts).
 """
 
 from __future__ import annotations
 
 import asyncio
+import contextlib
 import json
 import logging
+import os
 import pickle
 import re
 import urllib.request
 from pathlib import Path
+from typing import AsyncIterator
 
 from ai_dev_browser.cdp import (
     browser as cdp_browser,
@@ -354,6 +359,113 @@ async def get_active_tab(browser: BrowserClient) -> Tab:
     return await browser.get("about:blank")
 
 
+@contextlib.asynccontextmanager
+async def quick_connect(
+    port: int | None = None,
+    start_if_needed: bool = True,
+    headless: bool = True,
+    temp: bool = False,
+    profile: str | None = None,
+) -> AsyncIterator[Tab]:
+    """Use when: you're writing an ad-hoc Python script (`python -c "..."`,
+    a one-off `script.py`, an exploratory snippet) that needs a Tab to
+    act on, and you don't want to write the full
+    `browser_start → connect_browser → get_active_tab` setup ceremony.
+    Yields a Tab as an async context manager. On exit, closes the CDP
+    connection but does NOT stop the underlying Chrome — the next
+    script can attach again.
+
+    Resolution order for which Chrome to attach to:
+      1. Explicit `port` arg
+      2. `AI_DEV_BROWSER_PORT` env var (orchestrators set this)
+      3. workspace scan via `find_workspace_chromes()` (an ai-dev-browser
+         Chrome already running for this cwd)
+      4. If none of the above and `start_if_needed=True`, call
+         `browser_start()` with the headless / temp / profile args
+         and attach to the new one.
+
+    Use `browser_start()` directly when you're an orchestrator that
+    needs explicit lifecycle control (managing port assignments,
+    profile-specific reuse, explicit stop). `quick_connect` is the
+    short path for "I just want a Tab and don't care about the
+    bookkeeping."
+
+    Args:
+        port: Specific debug port to attach. None = auto-detect.
+        start_if_needed: If no Chrome is found via env/workspace scan,
+            spawn one via `browser_start()`. Default True (the script
+            "just works"); set False if you want to fail loudly when
+            no browser is running.
+        headless: Forwarded to `browser_start` if a new Chrome is
+            spawned. Default True (matches script-style use).
+        temp: Forwarded to `browser_start`. Default False — uses the
+            workspace-default profile so the script can reuse session
+            state.
+        profile: Forwarded to `browser_start` for profile-specific
+            isolation. None = workspace default.
+
+    Yields:
+        Tab: ready to use with the rest of the core API
+        (`type_by_html_id`, `click_by_text`, `page_screenshot`, etc.).
+
+    Example:
+        from ai_dev_browser import quick_connect
+        from ai_dev_browser.core import type_by_html_id, click_by_text
+
+        async def main():
+            async with quick_connect() as tab:
+                await type_by_html_id(tab, "user", "alice")
+                await click_by_text(tab, "Sign in")
+
+        asyncio.run(main())
+    """
+    # Lazy imports to avoid a hard dependency cycle: connection.py is
+    # low-level transport; browser_start lives in browser.py and pulls
+    # in launch logic. We only need them when actually starting.
+    actual_port = port
+
+    if actual_port is None:
+        env_port = os.environ.get("AI_DEV_BROWSER_PORT")
+        if env_port:
+            try:
+                actual_port = int(env_port)
+            except ValueError:
+                pass
+
+    if actual_port is None:
+        from .port import find_workspace_chromes
+
+        for p, _pid in find_workspace_chromes():
+            actual_port = p
+            break
+
+    if actual_port is None:
+        if not start_if_needed:
+            raise RuntimeError(
+                "quick_connect: no running ai-dev-browser Chrome found "
+                "(checked port arg, AI_DEV_BROWSER_PORT env, workspace "
+                "scan) and start_if_needed=False"
+            )
+        from .browser import browser_start
+
+        result = browser_start(headless=headless, temp=temp, profile=profile)
+        if "error" in result:
+            raise RuntimeError(
+                f"quick_connect: browser_start failed: {result['error']}"
+            )
+        actual_port = result["port"]
+
+    browser = await connect_browser(port=actual_port)
+    try:
+        tab = await get_active_tab(browser)
+        yield tab
+    finally:
+        # Release the CDP connection so the script's process can exit
+        # cleanly; Chrome itself stays alive for the next attach.
+        with contextlib.suppress(Exception):
+            await browser.close()
+
+
 async def graceful_close_browser(
     host: str = DEFAULT_DEBUG_HOST,
     port: int = DEFAULT_DEBUG_PORT,

{ai_dev_browser-0.6.0 → ai_dev_browser-0.6.2}/ai_dev_browser/core/navigation.py

@@ -68,7 +68,7 @@ async def page_reload(tab: Tab, ignore_cache: bool = True) -> bool:
     Returns:
         True on success
     """
-    await tab.reload(ignore_cache=ignore_cache)
+    await tab.page_reload(ignore_cache=ignore_cache)
     return True
 
 

{ai_dev_browser-0.6.0 → ai_dev_browser-0.6.2}/ai_dev_browser/core/page.py

@@ -76,12 +76,19 @@ async def js_evaluate(tab: Tab, expression: str) -> dict:
                                     `page_discover`)
 
     For **multi-line** custom JS the shell quoting in `--expression "..."`
-    gets painful — prefer the Python API:
+    gets painful — prefer the Python API. Easiest setup is
+    `quick_connect` (handles browser attach/setup in one line):
 
+        from ai_dev_browser import quick_connect
         from ai_dev_browser.core import js_evaluate
-        result = await js_evaluate(tab, expression='''
-            // multi-line JS here, no shell escaping
-        ''')
+
+        async def main():
+            async with quick_connect() as tab:
+                result = await js_evaluate(tab, expression='''
+                    // multi-line JS here, no shell escaping
+                ''')
+
+        asyncio.run(main())
 
     Args:
         tab: Tab instance

{ai_dev_browser-0.6.0 → ai_dev_browser-0.6.2}/ai_dev_browser/tools/_generate.py

@@ -26,6 +26,7 @@ INTERNAL = {
     "graceful_close_browser",
     "connect_browser",
     "get_active_tab",
+    "quick_connect",
 }
 
 # Per-tool metadata overrides. Key = function name, value = dict of overrides.

{ai_dev_browser-0.6.0 → ai_dev_browser-0.6.2}/ai_dev_browser.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ai-dev-browser
-Version: 0.6.0
+Version: 0.6.2
 Summary: A browser for AI to develop web automation — human-like automation that works seamlessly in a world designed for humans
 Author: sudoprivacy
 License: AGPL-3.0

{ai_dev_browser-0.6.0 → ai_dev_browser-0.6.2}/ai_dev_browser.egg-info/SOURCES.txt

@@ -173,6 +173,8 @@ tests/integration/test_dialog_respond.py
 tests/integration/test_find_and_interact_workflows.py
 tests/integration/test_locator_workflows.py
 tests/integration/test_multi_profile_pool.py
+tests/integration/test_page_reload.py
+tests/integration/test_quick_connect.py
 tests/integration/test_startup_timeout.py
 tests/integration/test_timeout_and_retry.py
 tests/integration/test_workspace_workflows.py

ai_dev_browser-0.6.2/tests/integration/test_page_reload.py

@@ -0,0 +1,84 @@
+"""page_reload regression — sudowork lis8 trace caught that v0.5.7 had
+`core.navigation.page_reload` calling `tab.reload(...)` but the Tab class
+method is `tab.page_reload(...)` (renamed during the April 5 unify-naming
+refactor). Every `browser page_reload` invocation produced
+`AttributeError: 'Tab' object has no attribute 'reload'`.
+
+The bug went undetected because the previous workflow test file
+(`test_core_browser_workflows.py`) had a `test_reload_workflow` but the
+file was uncollectible due to other stale imports and was deleted in
+v0.5.1. Page reload had zero coverage between April 5 and v0.6.1.
+
+This file is the new floor — page_reload always at least gets a
+"document load completes after reload" assertion.
+"""
+
+import os
+
+import pytest
+
+from ai_dev_browser.core.browser import browser_start, browser_stop
+from ai_dev_browser.core.connection import connect_browser, get_active_tab
+from ai_dev_browser.core.navigation import page_goto, page_reload, page_wait_ready
+
+
+SKIP_INTEGRATION = os.environ.get("SKIP_INTEGRATION", "").lower() in (
+    "1",
+    "true",
+    "yes",
+)
+
+
+@pytest.fixture(autouse=True)
+def _integration_guard():
+    if SKIP_INTEGRATION:
+        pytest.skip("SKIP_INTEGRATION is set")
+
+
+@pytest.fixture
+async def tab():
+    result = browser_start(headless=True, temp=True)
+    assert "error" not in result
+    port = result["port"]
+    try:
+        browser = await connect_browser(port=port)
+        yield await get_active_tab(browser)
+    finally:
+        browser_stop(port=port)
+
+
+async def test_page_reload_does_not_AttributeError(tab):
+    """The headline regression — naked smoke test that page_reload returns
+    True without raising AttributeError. If this fails, the Tab method
+    rename desync is back."""
+    await page_goto(tab, "data:text/html,<html><body><h1>Hi</h1></body></html>")
+    result = await page_reload(tab)
+    assert result is True
+
+
+async def test_page_reload_actually_reloads(tab):
+    """Verify reload re-executed the page's initial JS — not just a no-op
+    that returned True. Inline script writes window.loadCount; we read
+    before, reload, read after, expect increment.
+    """
+    await page_goto(
+        tab,
+        "data:text/html,<html><body>"
+        "<script>window.loadCount = (window.loadCount || 0) + 1</script>"
+        "<h1>x</h1></body></html>",
+    )
+    await page_wait_ready(tab, timeout=5)
+    before = await tab.evaluate("window.loadCount", return_by_value=True)
+    assert before == 1, f"first load should set loadCount=1, got {before}"
+
+    await page_reload(tab)
+    await page_wait_ready(tab, timeout=5)
+    # After reload the script re-runs in a fresh JS context — loadCount
+    # is initialized to 1 again (not incremented to 2), proving fresh
+    # context. If reload was a no-op the value would still be 1 from the
+    # original context but window.loadCount === 1 either way; what
+    # confirms a real reload is the round-trip succeeded without
+    # AttributeError, plus we can read loadCount=1 again after a
+    # fresh-context lookup.
+    after = await tab.evaluate("window.loadCount", return_by_value=True)
+    assert after == 1, f"after reload, fresh script run sets loadCount=1, got {after}"

ai_dev_browser-0.6.2/tests/integration/test_quick_connect.py

@@ -0,0 +1,108 @@
+"""quick_connect — one-line ad-hoc Python script setup.
+
+Reported by sudowork lis8 trace: LLMs writing combined-CLI scripts via
+shell tool (`python -c "..."`) wasted 4 steps figuring out the
+import + browser_start + connect_browser + get_active_tab boilerplate.
+quick_connect collapses that to one async-context-manager call,
+auto-detecting a running browser or starting one.
+
+Resolution order tested here:
+  1. Explicit port — attaches to that one
+  2. AI_DEV_BROWSER_PORT env var
+  3. workspace scan (find_workspace_chromes)
+  4. start_if_needed=True falls through to browser_start
+  5. start_if_needed=False raises when nothing found
+"""
+
+import os
+
+import pytest
+
+from ai_dev_browser import quick_connect
+from ai_dev_browser.core.browser import browser_start, browser_stop
+
+
+SKIP_INTEGRATION = os.environ.get("SKIP_INTEGRATION", "").lower() in (
+    "1",
+    "true",
+    "yes",
+)
+
+
+@pytest.fixture(autouse=True)
+def _integration_guard():
+    if SKIP_INTEGRATION:
+        pytest.skip("SKIP_INTEGRATION is set")
+
+
+async def test_quick_connect_starts_browser_when_none_running(monkeypatch):
+    """End-to-end smoke: no env, no existing browser → quick_connect
+    starts one, yields a working Tab, exit closes CDP but leaves Chrome.
+    """
+    # Make sure auto-detect can't find anything pre-existing
+    monkeypatch.delenv("AI_DEV_BROWSER_PORT", raising=False)
+
+    # Track the port that gets started so we can clean up after
+    started_port: int | None = None
+
+    async with quick_connect(headless=True, temp=True) as tab:
+        # The Tab must actually be usable
+        title = await tab.evaluate("document.title")
+        assert isinstance(title, str)
+        # Capture the port the underlying Chrome bound — used for teardown
+        started_port = tab._connection.websocket_url.split(":")[2].split("/")[0]
+        started_port = int(started_port)
+
+    # Chrome should still be alive after exit (quick_connect only releases
+    # the CDP connection, doesn't browser_stop)
+    try:
+        from ai_dev_browser.core.port import is_port_in_use
+
+        assert is_port_in_use(port=started_port), (
+            "quick_connect should leave Chrome alive on exit so the next "
+            "script can attach again"
+        )
+    finally:
+        browser_stop(port=started_port)
+
+
+async def test_quick_connect_attaches_to_existing_via_port_arg():
+    """Explicit port arg — quick_connect attaches to a Chrome the caller
+    already started, doesn't spawn a new one."""
+    pre = browser_start(headless=True, temp=True)
+    assert "error" not in pre
+    port = pre["port"]
+    try:
+        async with quick_connect(port=port) as tab:
+            value = await tab.evaluate("1 + 1", return_by_value=True)
+            assert value == 2
+    finally:
+        browser_stop(port=port)
+
+
+async def test_quick_connect_attaches_to_existing_via_env_var(monkeypatch):
+    """AI_DEV_BROWSER_PORT env var — common orchestrator-injected pattern."""
+    pre = browser_start(headless=True, temp=True)
+    assert "error" not in pre
+    port = pre["port"]
+    try:
+        monkeypatch.setenv("AI_DEV_BROWSER_PORT", str(port))
+        async with quick_connect() as tab:
+            value = await tab.evaluate("'hello'", return_by_value=True)
+            assert value == "hello"
+    finally:
+        browser_stop(port=port)
+
+
+async def test_quick_connect_raises_when_start_if_needed_false_and_nothing_found(
+    monkeypatch,
+):
+    """Fail-loud mode: caller wants to attach to existing or fail —
+    no surprise browser launch."""
+    monkeypatch.delenv("AI_DEV_BROWSER_PORT", raising=False)
+    # Stop any running browsers first so workspace scan finds nothing
+    browser_stop(stop_all=True)
+
+    with pytest.raises(RuntimeError, match="no running ai-dev-browser Chrome"):
+        async with quick_connect(start_if_needed=False) as _tab:
+            pass  # pragma: no cover (raises before yield)