computeruseprotocol 0.1.0__py3-none-any.whl

cup/__main__.py

@@ -0,0 +1,222 @@
+"""CLI for CUP tree capture: python -m cup"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import time
+
+from cup._router import detect_platform, get_adapter
+from cup.format import build_envelope, prune_tree, serialize_compact, serialize_overview
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="CUP: Capture accessibility tree in Computer Use Protocol format"
+    )
+    parser.add_argument("--depth", type=int, default=0, help="Max tree depth (0 = unlimited)")
+    parser.add_argument(
+        "--scope",
+        type=str,
+        default=None,
+        choices=["overview", "foreground", "desktop", "full"],
+        help="Capture scope (default: foreground)",
+    )
+    parser.add_argument(
+        "--app", type=str, default=None, help="Filter to window/app title containing this string"
+    )
+    parser.add_argument("--json-out", type=str, default=None, help="Write pruned CUP JSON to file")
+    parser.add_argument(
+        "--full-json-out", type=str, default=None, help="Write full (unpruned) CUP JSON to file"
+    )
+    parser.add_argument("--compact-out", type=str, default=None, help="Write compact text to file")
+    parser.add_argument(
+        "--verbose",
+        action="store_true",
+        help="Print diagnostics (timing, role distribution, sizes)",
+    )
+    parser.add_argument(
+        "--platform",
+        type=str,
+        default=None,
+        choices=["windows", "macos", "linux", "web"],
+        help="Force platform (default: auto-detect)",
+    )
+    parser.add_argument(
+        "--cdp-port", type=int, default=None, help="CDP port for web platform (default: 9222)"
+    )
+    parser.add_argument(
+        "--cdp-host", type=str, default=None, help="CDP host for web platform (default: localhost)"
+    )
+    args = parser.parse_args()
+
+    scope = args.scope or "foreground"
+    verbose = args.verbose
+
+    max_depth = args.depth if args.depth > 0 else 999
+    platform = args.platform or detect_platform()
+
+    # Pass CDP connection args via env vars for the web adapter
+    if platform == "web":
+        if args.cdp_port:
+            os.environ["CUP_CDP_PORT"] = str(args.cdp_port)
+        if args.cdp_host:
+            os.environ["CUP_CDP_HOST"] = args.cdp_host
+
+    if verbose:
+        print(f"=== CUP Tree Capture ({platform}) ===")
+
+    adapter = get_adapter(platform)
+    sw, sh, scale = adapter.get_screen_info()
+
+    if verbose:
+        scale_str = f" @{scale}x" if scale != 1.0 else ""
+        print(f"Screen: {sw}x{sh}{scale_str}")
+
+    # -- Overview scope: window list only, no tree walking --
+    if scope == "overview":
+        t0 = time.perf_counter()
+        window_list = adapter.get_window_list()
+        t_enum = (time.perf_counter() - t0) * 1000
+
+        if verbose:
+            print(f"Scope: overview ({len(window_list)} windows, {t_enum:.1f} ms)")
+
+        overview_str = serialize_overview(
+            window_list,
+            platform=platform,
+            screen_w=sw,
+            screen_h=sh,
+        )
+        print(overview_str)
+
+        if args.compact_out:
+            with open(args.compact_out, "w", encoding="utf-8") as f:
+                f.write(overview_str)
+            if verbose:
+                print(f"Overview written to {args.compact_out}")
+        return
+
+    # -- Window enumeration --
+    t0 = time.perf_counter()
+    window_list = None
+
+    if scope == "foreground":
+        windows = [adapter.get_foreground_window()]
+        window_list = adapter.get_window_list()
+        if verbose:
+            print(f'Scope: foreground ("{windows[0]["title"]}")')
+    elif scope == "desktop":
+        desktop_win = adapter.get_desktop_window()
+        if desktop_win is None:
+            if verbose:
+                print("No desktop window found on this platform. Falling back to overview.")
+            window_list = adapter.get_window_list()
+            overview_str = serialize_overview(
+                window_list,
+                platform=platform,
+                screen_w=sw,
+                screen_h=sh,
+            )
+            print(overview_str)
+            return
+        windows = [desktop_win]
+        if verbose:
+            print("Scope: desktop")
+    else:  # "full"
+        windows = adapter.get_all_windows()
+        if args.app:
+            windows = [w for w in windows if args.app.lower() in w["title"].lower()]
+            if not windows:
+                print(f"No window found matching '{args.app}'")
+                return
+        if verbose:
+            print(f"Scope: full ({len(windows)} window(s))")
+    t_enum = (time.perf_counter() - t0) * 1000
+
+    # -- Tree capture --
+    t0 = time.perf_counter()
+    tree, stats, _refs = adapter.capture_tree(windows, max_depth=max_depth)
+    t_walk = (time.perf_counter() - t0) * 1000
+
+    if verbose:
+        print(f"Captured {stats['nodes']} nodes in {t_walk:.1f} ms (enum: {t_enum:.1f} ms)")
+        print(f"Max depth: {stats['max_depth']}")
+
+    # -- Envelope --
+    app_name = windows[0]["title"] if len(windows) == 1 else None
+    app_pid = windows[0]["pid"] if len(windows) == 1 else None
+    app_bundle_id = windows[0].get("bundle_id") if len(windows) == 1 else None
+
+    # Collect WebMCP tools when available (web platform)
+    tools = None
+    if hasattr(adapter, "get_last_tools"):
+        tools = adapter.get_last_tools() or None
+
+    envelope = build_envelope(
+        tree,
+        platform=platform,
+        scope=scope,
+        screen_w=sw,
+        screen_h=sh,
+        screen_scale=scale,
+        app_name=app_name,
+        app_pid=app_pid,
+        app_bundle_id=app_bundle_id,
+        tools=tools,
+    )
+
+    # -- Compact text to stdout (default) --
+    compact_str = serialize_compact(envelope, window_list=window_list)
+    print(compact_str)
+
+    # -- Verbose diagnostics --
+    if verbose:
+        json_str = json.dumps(envelope, ensure_ascii=False)
+        json_kb = len(json_str) / 1024
+        compact_kb = len(compact_str) / 1024
+        print(f"JSON size: {json_kb:.1f} KB | Compact size: {compact_kb:.1f} KB")
+
+        print("\nRole distribution (top 15):")
+        for role, count in sorted(stats["roles"].items(), key=lambda kv: -kv[1])[:15]:
+            print(f"  {role:45s} {count:6d}")
+
+        if tools:
+            print(f"\nWebMCP tools ({len(tools)}):")
+            for tool in tools:
+                desc = tool.get("description", "")
+                desc_str = f" - {desc}" if desc else ""
+                print(f"  {tool['name']}{desc_str}")
+
+    # -- File output options --
+    if args.json_out:
+        pruned_tree = prune_tree(envelope["tree"])
+        pruned_envelope = {**envelope, "tree": pruned_tree}
+        with open(args.json_out, "w", encoding="utf-8") as f:
+            json.dump(pruned_envelope, f, indent=2, ensure_ascii=False)
+        if verbose:
+            pruned_kb = len(json.dumps(pruned_envelope, ensure_ascii=False)) / 1024
+            print(f"\nPruned JSON written to {args.json_out} ({pruned_kb:.1f} KB)")
+
+    if args.full_json_out:
+        with open(args.full_json_out, "w", encoding="utf-8") as f:
+            json.dump(envelope, f, indent=2, ensure_ascii=False)
+        if verbose:
+            json_kb = len(json.dumps(envelope, ensure_ascii=False)) / 1024
+            print(f"Full JSON written to {args.full_json_out} ({json_kb:.1f} KB)")
+
+    if args.compact_out:
+        with open(args.compact_out, "w", encoding="utf-8") as f:
+            f.write(compact_str)
+        if verbose:
+            json_kb = len(json.dumps(envelope, ensure_ascii=False)) / 1024
+            compact_kb = len(compact_str) / 1024
+            ratio = (1 - compact_kb / json_kb) * 100 if json_kb > 0 else 0
+            print(
+                f"Compact written to {args.compact_out} ({compact_kb:.1f} KB, {ratio:.0f}% smaller)"
+            )
+
+
+if __name__ == "__main__":
+    main()

cup/_base.py

@@ -0,0 +1,123 @@
+"""Abstract base for platform adapters."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class PlatformAdapter(ABC):
+    """Interface that each platform tree-capture backend must implement.
+
+    Subclasses handle all platform-specific initialization, window
+    enumeration, tree walking, and CUP node construction.  The router
+    calls only the methods defined here.
+    """
+
+    # ---- identity --------------------------------------------------------
+
+    @property
+    @abstractmethod
+    def platform_name(self) -> str:
+        """Return the platform identifier used in CUP envelopes.
+
+        Must be one of: 'windows', 'macos', 'linux', 'web', 'android', 'ios'.
+        """
+        ...
+
+    # ---- lifecycle -------------------------------------------------------
+
+    @abstractmethod
+    def initialize(self) -> None:
+        """Perform any one-time setup (COM init, pyobjc bootstrap, etc.).
+
+        Called once before the first capture.  Implementations should be
+        idempotent (safe to call multiple times).
+        """
+        ...
+
+    # ---- screen ----------------------------------------------------------
+
+    @abstractmethod
+    def get_screen_info(self) -> tuple[int, int, float]:
+        """Return (width, height, scale_factor) of the primary display."""
+        ...
+
+    # ---- window enumeration ----------------------------------------------
+
+    @abstractmethod
+    def get_foreground_window(self) -> dict[str, Any]:
+        """Return metadata about the foreground/focused window.
+
+        Must return a dict with at least:
+            {
+                "handle": <platform-specific window handle/ref>,
+                "title": str,
+                "pid": int | None,
+                "bundle_id": str | None,
+            }
+        """
+        ...
+
+    @abstractmethod
+    def get_all_windows(self) -> list[dict[str, Any]]:
+        """Return metadata dicts for all visible top-level windows.
+
+        Same dict shape as get_foreground_window().
+        """
+        ...
+
+    # ---- window overview -------------------------------------------------
+
+    @abstractmethod
+    def get_window_list(self) -> list[dict[str, Any]]:
+        """Return lightweight metadata for all visible windows.
+
+        Does NOT perform any tree walking.  Must be near-instant.
+
+        Each dict contains::
+
+            {
+                "title": str,
+                "pid": int | None,
+                "bundle_id": str | None,
+                "foreground": bool,
+                "bounds": {"x": int, "y": int, "w": int, "h": int} | None,
+            }
+        """
+        ...
+
+    @abstractmethod
+    def get_desktop_window(self) -> dict[str, Any] | None:
+        """Return metadata for the desktop surface window.
+
+        Returns a window metadata dict (same shape as get_foreground_window)
+        pointing at the desktop surface (icons, widgets), or None if the
+        platform has no desktop concept (e.g., web).
+        """
+        ...
+
+    # ---- tree capture ----------------------------------------------------
+
+    @abstractmethod
+    def capture_tree(
+        self,
+        windows: list[dict[str, Any]],
+        *,
+        max_depth: int = 999,
+    ) -> tuple[list[dict], dict, dict[str, Any]]:
+        """Walk the accessibility tree for the given windows.
+
+        Args:
+            windows: List of window metadata dicts (from get_foreground_window
+                     or get_all_windows).
+            max_depth: Maximum tree depth to walk.
+
+        Returns:
+            (tree_roots, stats, refs) where:
+                tree_roots: list of CUP node dicts (the "tree" field of the envelope)
+                stats: dict with at least {"nodes": int, "max_depth": int}
+                refs: dict mapping element IDs (e.g. "e14") to native platform
+                      element references, used by the action execution layer
+        """
+        ...

cup/_router.py

@@ -0,0 +1,63 @@
+"""Platform auto-detection and adapter dispatch."""
+
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from cup._base import PlatformAdapter
+
+
+def detect_platform() -> str:
+    """Return the current platform identifier."""
+    if sys.platform == "win32":
+        return "windows"
+    elif sys.platform == "darwin":
+        return "macos"
+    elif sys.platform.startswith("linux"):
+        return "linux"
+    else:
+        raise RuntimeError(f"Unsupported platform: {sys.platform}")
+
+
+def get_adapter(platform: str | None = None) -> PlatformAdapter:
+    """Return a fresh platform adapter instance.
+
+    Each call creates and initializes a new adapter. Callers (e.g., Session)
+    are responsible for holding onto the instance for reuse.
+
+    Args:
+        platform: Force a specific platform ('windows', 'macos', 'web').
+                  If None, auto-detects from sys.platform.
+
+    Raises:
+        RuntimeError: If the platform is unsupported or dependencies are missing.
+    """
+    if platform is None:
+        platform = detect_platform()
+
+    if platform == "windows":
+        from cup.platforms.windows import WindowsAdapter
+
+        adapter = WindowsAdapter()
+    elif platform == "macos":
+        from cup.platforms.macos import MacosAdapter
+
+        adapter = MacosAdapter()
+    elif platform == "linux":
+        from cup.platforms.linux import LinuxAdapter
+
+        adapter = LinuxAdapter()
+    elif platform == "web":
+        from cup.platforms.web import WebAdapter
+
+        adapter = WebAdapter()
+    else:
+        raise RuntimeError(
+            f"No adapter available for platform '{platform}'. "
+            f"Currently supported: windows, macos, linux, web."
+        )
+
+    adapter.initialize()
+    return adapter

cup/actions/__init__.py

@@ -0,0 +1,9 @@
+"""CUP action execution layer.
+
+Provides cross-platform action dispatch using element references
+captured during tree walks.
+"""
+
+from cup.actions.executor import ActionExecutor, ActionResult
+
+__all__ = ["ActionExecutor", "ActionResult"]

cup/actions/_handler.py

@@ -0,0 +1,62 @@
+"""Abstract base for platform-specific action handlers."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from cup.actions.executor import ActionResult
+
+
+class ActionHandler(ABC):
+    """Interface for platform-specific action execution.
+
+    Each platform implements this to translate CUP canonical actions
+    (click, type, toggle, etc.) into native API calls.
+    """
+
+    @abstractmethod
+    def action(
+        self,
+        native_ref: Any,
+        action: str,
+        params: dict[str, Any],
+    ) -> ActionResult:
+        """Execute a CUP action using the native element reference.
+
+        Args:
+            native_ref: Platform-specific element reference from ref_map.
+            action: CUP canonical action name (click, type, toggle, etc.).
+            params: Action parameters (e.g., value for type, direction for scroll).
+
+        Returns:
+            ActionResult with success status and message.
+        """
+        ...
+
+    @abstractmethod
+    def press(self, combo: str) -> ActionResult:
+        """Send a keyboard combination to the focused window.
+
+        Args:
+            combo: Key combination string (e.g., "ctrl+s", "enter", "alt+f4").
+
+        Returns:
+            ActionResult with success status and message.
+        """
+        ...
+
+    @abstractmethod
+    def open_app(self, name: str) -> ActionResult:
+        """Open an application by name.
+
+        Implementations should discover installed apps, fuzzy-match the
+        name, launch the best match, and confirm the window appeared.
+
+        Args:
+            name: Application name to open (fuzzy matched).
+
+        Returns:
+            ActionResult with success status and message.
+        """
+        ...

cup/actions/_keys.py

@@ -0,0 +1,56 @@
+"""Shared key combo parsing and normalization."""
+
+from __future__ import annotations
+
+# Modifier key names (normalized)
+MODIFIERS = frozenset({"ctrl", "alt", "shift", "win", "cmd", "meta", "super"})
+
+# Alias normalization
+_ALIASES: dict[str, str] = {
+    "return": "enter",
+    "esc": "escape",
+    "del": "delete",
+    "bs": "backspace",
+    "cmd": "meta",
+    "super": "meta",
+    "win": "meta",
+    "pgup": "pageup",
+    "pgdn": "pagedown",
+    "pgdown": "pagedown",
+}
+
+
+def parse_combo(combo: str) -> tuple[list[str], list[str]]:
+    """Parse a key combo string into (modifiers, keys).
+
+    Examples::
+
+        >>> parse_combo("ctrl+s")
+        (['ctrl'], ['s'])
+        >>> parse_combo("ctrl+shift+p")
+        (['ctrl', 'shift'], ['p'])
+        >>> parse_combo("enter")
+        ([], ['enter'])
+        >>> parse_combo("a")
+        ([], ['a'])
+
+    Args:
+        combo: Key combination string, parts joined with "+".
+
+    Returns:
+        (modifiers, keys) where modifiers are normalized modifier names
+        and keys are the non-modifier key names.
+    """
+    parts = [p.strip().lower() for p in combo.split("+") if p.strip()]
+    modifiers: list[str] = []
+    keys: list[str] = []
+
+    for part in parts:
+        # Normalize aliases
+        normalized = _ALIASES.get(part, part)
+        if normalized in ("ctrl", "alt", "shift", "meta"):
+            modifiers.append(normalized)
+        else:
+            keys.append(normalized)
+
+    return modifiers, keys