browser-tools 0.2.0__tar.gz → 0.3.0__tar.gz

{browser_tools-0.2.0 → browser_tools-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: browser-tools
-Version: 0.2.0
+Version: 0.3.0
 Summary: Browser automation, debugging, and anti-detect browsing CLI
 Project-URL: Homepage, https://github.com/dungle-scrubs/browser-tools
 Project-URL: Repository, https://github.com/dungle-scrubs/browser-tools

{browser_tools-0.2.0 → browser_tools-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "browser-tools"
-version = "0.2.0"
+version = "0.3.0"
 description = "Browser automation, debugging, and anti-detect browsing CLI"
 readme = "README.md"
 license = "MIT"

{browser_tools-0.2.0 → browser_tools-0.3.0}/src/browser_tools/cli.py

@@ -27,7 +27,7 @@ import argparse
 import json
 import sys
 
-from . import curated, events, lifecycle, list_verbs, passthrough
+from . import curated, events, lifecycle, list_verbs, passthrough, user_settings
 from .lifecycle import LifecycleError
 from .passthrough import UsageError as PassthroughUsageError
 
@@ -48,6 +48,7 @@ _KNOWN_VERBS = {
     "stop",
     "cleanup",
     "guide",
+    "window-border",
     "help",
     "attach",
     "wait",
@@ -89,7 +90,10 @@ def build_parser() -> argparse.ArgumentParser:
     launch.add_argument(
         "--no-window-border",
         action="store_true",
-        help="Do not draw the agent-window marking border",
+        help=(
+            "Do not mark this window at all (no tab-title prefix, no border). To keep "
+            "the title prefix and only hide the border, use: window-border off"
+        ),
     )
     launch.add_argument(
         "browser_args",
@@ -108,6 +112,19 @@ def build_parser() -> argparse.ArgumentParser:
     sub.add_parser("cleanup", help="Remove stale registry entries and session dirs")
     sub.add_parser("guide", help="Print the bundled agent manual")
 
+    border = sub.add_parser(
+        "window-border",
+        help="Show, or persistently turn on/off, the border drawn in marked windows",
+        description=(
+            "The window marker draws a colored border and a corner badge over the page "
+            "of every window it marks. They cover the page's outer edge and top-left "
+            "corner. 'off' removes them from every running browser within a second and "
+            "keeps them off for later launches, until 'on'. The tab-title prefix is not "
+            "affected. With no argument, prints the current setting."
+        ),
+    )
+    border.add_argument("state", nargs="?", choices=["on", "off"], help="New setting")
+
     help_cmd = sub.add_parser(
         "help", help="Live CDP protocol help from a running instance, or static usage"
     )
@@ -262,13 +279,27 @@ def _print_json(payload: object) -> None:
     print(json.dumps(payload, indent=2))
 
 
-def _strip_arg_separator(browser_args: list[str] | None) -> list[str]:
-    """Drop the leading ``--`` argparse.REMAINDER keeps in front of BROWSER_ARGS."""
-    if not browser_args:
+def _browser_args_from_remainder(remainder: list[str] | None) -> list[str]:
+    """Return the verbatim BROWSER_ARGS that follow ``--``, or reject the remainder.
+
+    ``launch`` takes no positional arguments. argparse.REMAINDER starts
+    collecting at the first bare token and swallows every option after it, so
+    ``bt launch e2e-01 --headless`` would silently hand ``e2e-01 --headless``
+    to Chrome: Chrome opens ``http://e2e-01/`` and runs headless while
+    browser-tools believes the launch is headed (spawning the supervisor,
+    marking the window). A remainder that does not start with ``--`` is
+    therefore a usage error, not browser args.
+    """
+    if not remainder:
         return []
-    if browser_args[0] == "--":
-        return browser_args[1:]
-    return browser_args
+    if remainder[0] == "--":
+        return remainder[1:]
+    raise PassthroughUsageError(
+        f"launch takes no positional arguments (got {remainder[0]!r}); instance "
+        f"names are assigned by the registry; use --profile NAME to bind a named "
+        f"profile. Flags for the browser itself go after '--', e.g. "
+        f"bt launch --headless -- --proxy-server=host:port"
+    )
 
 
 def _run(args: argparse.Namespace) -> int:
@@ -284,7 +315,7 @@ def _run(args: argparse.Namespace) -> int:
             port=args.port,
             fingerprint=args.fingerprint,
             window_border=not args.no_window_border,
-            browser_args=_strip_arg_separator(args.browser_args),
+            browser_args=_browser_args_from_remainder(args.browser_args),
             registry_path=registry_path,
         )
         _print_json(
@@ -322,6 +353,18 @@ def _run(args: argparse.Namespace) -> int:
         print(lifecycle.guide_text())
         return EXIT_OK
 
+    if args.command == "window-border":
+        if args.state is not None:
+            user_settings.set_window_border(args.state == user_settings.ON)
+        enabled = user_settings.window_border_enabled()
+        _print_json(
+            {
+                "window_border": user_settings.ON if enabled else user_settings.OFF,
+                "settings_path": str(user_settings.settings_path()),
+            }
+        )
+        return EXIT_OK
+
     if args.command == "help":
         instance, query = passthrough.resolve_help_args(args.args, registry_path=registry_path)
         passthrough.run_help(instance, query, registry_path=registry_path)

{browser_tools-0.2.0 → browser_tools-0.3.0}/src/browser_tools/core/launcher.py

@@ -7,9 +7,12 @@
 # `binary` parameter was added to launch_browser so the CLI front can resolve
 # the --channel policy flag to a Chrome binary before launch, and (#36) a
 # `user_data_dir` parameter so the CLI front can bind a persistent per-profile
-# user-data-dir instead of the throwaway session dir. Intra-package imports are
-# rewritten to browser_tools.core. Otherwise unchanged from chrome-agent
-# v0.5.7. See RFC-01, section "Vendoring rules".
+# user-data-dir instead of the throwaway session dir. A headed launch starts
+# with no window (--no-startup-window) and opens its first window in the
+# background over CDP, so the launch never takes the user's focus (see
+# _open_first_window). Intra-package imports are rewritten to
+# browser_tools.core. Otherwise unchanged from chrome-agent v0.5.7. See RFC-01,
+# section "Vendoring rules".
 
 """Browser launch and session management.
 
@@ -167,6 +170,8 @@ async def launch_browser(
     ]
     if headless:
         args.append("--headless=new")
+    else:
+        args.append("--no-startup-window")
     if extra_args:
         args.extend(extra_args)
 
@@ -214,6 +219,19 @@ async def launch_browser(
         process.kill()
         raise TimeoutError("Browser did not start within 30 seconds")
 
+    if not headless:
+        try:
+            await _open_first_window(port=port)
+        except BaseException as exc:
+            # Nothing is registered yet, so a browser left running here would be
+            # an orphan no verb can see or stop. BaseException, not Exception: a
+            # launch cancelled while this awaits (Ctrl-C, a cancelled task)
+            # leaves the same orphan, and CancelledError is not an Exception.
+            process.kill()
+            if isinstance(exc, asyncio.CancelledError):
+                raise
+            raise RuntimeError(f"Browser started but its first window did not open: {exc}") from exc
+
     # Phase 6: Pin to desktop (Linux/X11, best-effort)
     if pin_to_desktop and not headless:
         await _move_to_launching_desktop(pid=process.pid)
@@ -236,12 +254,13 @@ async def launch_browser(
     # detached process -- it must survive the caller exiting (fire-and-forget
     # launch model) -- that holds a CDP connection and, when the browser/window
     # closes, retires the instance from the registry (and removes its session
-    # dir). While the browser is alive it also draws the window border, unless:
+    # dir). While the browser is alive it also marks the window (tab title
+    # prefix), unless:
     #   - --no-window-border (window_border is False), or
-    #   - a fingerprint profile is active: the in-page border/badge/title are
-    #     page-observable (a findable host element + a modified document.title),
-    #     and bot-defended sites -- exactly where fingerprinting is used -- are
-    #     where DOM/title-diffing detectors live. See the detection audit.
+    #   - a fingerprint profile is active: the title prefix is page-observable
+    #     (a modified document.title), and bot-defended sites -- exactly where
+    #     fingerprinting is used -- are where title-diffing detectors live. See
+    #     the detection audit.
     # Headless launches get no supervisor (no window to close or mark); their
     # registry entries are reclaimed by the launch-time prune above / cleanup.
     if not headless:
@@ -256,6 +275,24 @@ async def launch_browser(
     return instance_info
 
 
+async def _open_first_window(*, port: int) -> None:
+    """Open the browser's first window in the background.
+
+    Chrome started normally opens a window and makes itself the active app,
+    which takes keyboard focus and the window manager's focus from whatever
+    the user is doing (measured on macOS; ``open -g`` does not prevent it).
+    A browser started with ``--no-startup-window`` opens nothing, and a window
+    created over CDP with ``background`` set leaves focus where it is.
+    """
+    from .cdp_client import CDPClient, get_ws_url
+
+    async with CDPClient(ws_url=get_ws_url(port=port, target_type="browser")) as cdp:
+        await cdp.send(
+            method="Target.createTarget",
+            params={"url": "about:blank", "newWindow": True, "background": True},
+        )
+
+
 def cleanup_sessions(registry_path: str | None = None) -> list[str]:
     """Remove stale instances and their session directories.