cmdop 0.1.28__py3-none-any.whl → 0.1.30__py3-none-any.whl

cmdop/__init__.py

@@ -120,6 +120,11 @@ from cmdop.helpers import (
     NetworkAnalyzer,
     NetworkSnapshot,
     RequestSnapshot,
+    # Desktop management
+    ensure_desktop_running,
+    start_desktop,
+    handle_cmdop_error,
+    with_auto_restart,
 )
 from cmdop.logging import (
     get_logger,
@@ -128,7 +133,7 @@ from cmdop.logging import (
     get_log_dir,
 )
 
-__version__ = "0.1.28"
+__version__ = "0.1.30"
 
 __all__ = [
     # Version
@@ -225,6 +230,11 @@ __all__ = [
     "NetworkAnalyzer",
     "NetworkSnapshot",
     "RequestSnapshot",
+    # Desktop management
+    "ensure_desktop_running",
+    "start_desktop",
+    "handle_cmdop_error",
+    "with_auto_restart",
     # Logging
     "get_logger",
     "setup_logging",

cmdop/helpers/__init__.py

@@ -5,9 +5,23 @@ from cmdop.helpers.network_analyzer import (
     NetworkSnapshot,
     RequestSnapshot,
 )
+from cmdop.helpers.desktop import (
+    ensure_desktop_running,
+    start_desktop,
+    handle_cmdop_error,
+    with_auto_restart,
+    get_cmdop_app_path,
+)
 
 __all__ = [
+    # Network
     "NetworkAnalyzer",
     "NetworkSnapshot",
     "RequestSnapshot",
+    # Desktop management
+    "ensure_desktop_running",
+    "start_desktop",
+    "handle_cmdop_error",
+    "with_auto_restart",
+    "get_cmdop_app_path",
 ]

cmdop/helpers/desktop.py

@@ -0,0 +1,350 @@
+"""
+CMDOP Desktop management helpers.
+
+Cross-platform utilities for starting, stopping, and ensuring
+CMDOP Desktop is running.
+"""
+
+from __future__ import annotations
+
+import platform
+import subprocess
+import sys
+import time
+from pathlib import Path
+from typing import Callable, TypeVar
+
+from cmdop.exceptions import AgentNotRunningError, StalePortFileError
+from cmdop.transport.discovery import discover_agent, cleanup_stale_discovery
+
+T = TypeVar("T")
+
+
+# =============================================================================
+# Platform-specific paths
+# =============================================================================
+
+def get_cmdop_app_path() -> Path | None:
+    """Get platform-specific path to CMDOP Desktop app."""
+    system = platform.system()
+
+    if system == "Darwin":
+        path = Path("/Applications/CMDOP.app")
+        if path.exists():
+            return path
+        # Check user Applications
+        user_path = Path.home() / "Applications" / "CMDOP.app"
+        if user_path.exists():
+            return user_path
+
+    elif system == "Windows":
+        # Common Windows install locations
+        paths = [
+            Path(r"C:\Program Files\CMDOP\CMDOP.exe"),
+            Path(r"C:\Program Files (x86)\CMDOP\CMDOP.exe"),
+            Path.home() / "AppData" / "Local" / "Programs" / "CMDOP" / "CMDOP.exe",
+        ]
+        for path in paths:
+            if path.exists():
+                return path
+
+    elif system == "Linux":
+        # Linux: check if cmdop binary is available
+        try:
+            result = subprocess.run(
+                ["which", "cmdop"],
+                capture_output=True,
+                text=True,
+            )
+            if result.returncode == 0:
+                return Path(result.stdout.strip())
+        except Exception:
+            pass
+
+    return None
+
+
+# =============================================================================
+# Core functions
+# =============================================================================
+
+def start_desktop(timeout: float = 15.0, quiet: bool = False) -> bool:
+    """
+    Start CMDOP Desktop application.
+
+    Cross-platform function that starts CMDOP Desktop and waits
+    for the agent to become available.
+
+    Args:
+        timeout: Maximum time to wait for agent to start (seconds)
+        quiet: If True, suppress output messages
+
+    Returns:
+        True if agent started successfully, False otherwise
+    """
+    system = platform.system()
+
+    def log(msg: str) -> None:
+        if not quiet:
+            print(msg)
+
+    log("🔄 Starting CMDOP Desktop...")
+
+    try:
+        if system == "Darwin":
+            app_path = get_cmdop_app_path()
+            if app_path:
+                subprocess.Popen(
+                    ["open", str(app_path)],
+                    stdout=subprocess.DEVNULL,
+                    stderr=subprocess.DEVNULL,
+                )
+            else:
+                log("❌ CMDOP.app not found in /Applications")
+                return False
+
+        elif system == "Windows":
+            app_path = get_cmdop_app_path()
+            # DETACHED_PROCESS = 0x00000008
+            detached_process = 0x00000008
+            if app_path:
+                subprocess.Popen(
+                    [str(app_path)],
+                    stdout=subprocess.DEVNULL,
+                    stderr=subprocess.DEVNULL,
+                    creationflags=detached_process,
+                )
+            else:
+                # Try start command as fallback
+                subprocess.Popen(
+                    ["cmd", "/c", "start", "", "CMDOP"],
+                    stdout=subprocess.DEVNULL,
+                    stderr=subprocess.DEVNULL,
+                    shell=True,
+                )
+
+        elif system == "Linux":
+            # Linux: start cmdop serve in background
+            subprocess.Popen(
+                ["cmdop", "serve"],
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                start_new_session=True,
+            )
+
+        else:
+            log(f"❌ Unsupported platform: {system}")
+            return False
+
+    except Exception as e:
+        log(f"❌ Failed to start CMDOP: {e}")
+        return False
+
+    log("⏳ Waiting for CMDOP to initialize...")
+
+    # Poll until agent is available
+    start_time = time.time()
+    last_dot_time = start_time
+
+    while time.time() - start_time < timeout:
+        result = discover_agent(verify_alive=True)
+        if result.found:
+            log("✅ CMDOP Desktop started successfully")
+            return True
+
+        # Print dots to show progress
+        if not quiet and time.time() - last_dot_time >= 1.0:
+            print(".", end="", flush=True)
+            last_dot_time = time.time()
+
+        time.sleep(0.3)
+
+    if not quiet:
+        print()  # Newline after dots
+    log(f"❌ CMDOP did not start within {timeout}s")
+    return False
+
+
+def ensure_desktop_running(
+    timeout: float = 15.0,
+    auto_start: bool = True,
+    exit_on_failure: bool = True,
+) -> bool:
+    """
+    Ensure CMDOP Desktop is running, starting it if needed.
+
+    This is the main function to use before browser operations.
+    Handles stale discovery files automatically.
+
+    Args:
+        timeout: Time to wait for agent if starting
+        auto_start: If True, attempt to start CMDOP if not running
+        exit_on_failure: If True, call sys.exit(1) on failure
+
+    Returns:
+        True if CMDOP is running
+
+    Raises:
+        SystemExit: If exit_on_failure=True and CMDOP cannot be started
+
+    Example:
+        >>> from cmdop.helpers import ensure_desktop_running
+        >>> ensure_desktop_running()  # Starts CMDOP if needed
+        >>> # Now safe to use browser
+        >>> client = CMDOPClient.local()
+    """
+    result = discover_agent(verify_alive=True)
+
+    if result.found:
+        return True
+
+    # Handle stale discovery file
+    if result.discovery_path:
+        print(f"⚠️  Cleaning stale discovery file: {result.discovery_path}")
+        cleanup_stale_discovery(result.discovery_path)
+
+    print("⚠️  CMDOP Desktop is not running")
+
+    if not auto_start:
+        if exit_on_failure:
+            print("\nStart CMDOP Desktop manually:")
+            _print_start_instructions()
+            sys.exit(1)
+        return False
+
+    # Try to start
+    if start_desktop(timeout=timeout):
+        return True
+
+    if exit_on_failure:
+        print("\n💡 Try starting CMDOP Desktop manually:")
+        _print_start_instructions()
+        sys.exit(1)
+
+    return False
+
+
+def handle_cmdop_error(
+    error: Exception,
+    auto_restart: bool = True,
+    exit_on_failure: bool = True,
+) -> bool:
+    """
+    Handle CMDOP connection errors with auto-restart.
+
+    Use this in except blocks to handle AgentNotRunningError
+    and StalePortFileError gracefully.
+
+    Args:
+        error: The exception that was raised
+        auto_restart: If True, attempt to restart CMDOP
+        exit_on_failure: If True, call sys.exit(1) if restart fails
+
+    Returns:
+        True if CMDOP was restarted successfully
+
+    Example:
+        >>> try:
+        ...     client = CMDOPClient.local()
+        ...     session = client.browser.create_session()
+        ... except (StalePortFileError, AgentNotRunningError) as e:
+        ...     if handle_cmdop_error(e):
+        ...         # Retry the operation
+        ...         client = CMDOPClient.local()
+    """
+    if isinstance(error, StalePortFileError):
+        print(f"\n⚠️  CMDOP Desktop crashed (stale file: {error.discovery_path})")
+        error.cleanup()
+    elif isinstance(error, AgentNotRunningError):
+        print("\n⚠️  CMDOP Desktop is not running")
+    else:
+        # Unknown error, re-raise
+        raise error
+
+    if not auto_restart:
+        if exit_on_failure:
+            print("\nStart CMDOP Desktop:")
+            _print_start_instructions()
+            sys.exit(1)
+        return False
+
+    if start_desktop():
+        return True
+
+    if exit_on_failure:
+        print("\n💡 Try starting CMDOP Desktop manually:")
+        _print_start_instructions()
+        sys.exit(1)
+
+    return False
+
+
+def with_auto_restart(
+    func: Callable[..., T],
+    *args,
+    max_retries: int = 1,
+    **kwargs,
+) -> T:
+    """
+    Execute function with automatic CMDOP restart on failure.
+
+    Wraps a function that uses CMDOP and automatically handles
+    connection errors by restarting CMDOP Desktop.
+
+    Args:
+        func: Function to execute
+        *args: Arguments to pass to function
+        max_retries: Maximum restart attempts
+        **kwargs: Keyword arguments to pass to function
+
+    Returns:
+        Result of the function
+
+    Example:
+        >>> def parse_page():
+        ...     client = CMDOPClient.local()
+        ...     with client.browser.create_session() as session:
+        ...         session.navigate("https://example.com")
+        ...         return session.get_text("body")
+        ...
+        >>> result = with_auto_restart(parse_page)
+    """
+    last_error: Exception | None = None
+
+    for attempt in range(max_retries + 1):
+        try:
+            return func(*args, **kwargs)
+        except (StalePortFileError, AgentNotRunningError) as e:
+            last_error = e
+
+            if attempt < max_retries:
+                print(f"\n🔄 CMDOP error (attempt {attempt + 1}/{max_retries + 1})")
+                if handle_cmdop_error(e, auto_restart=True, exit_on_failure=False):
+                    continue
+
+            # Last attempt failed
+            handle_cmdop_error(e, auto_restart=False, exit_on_failure=True)
+
+    # Should not reach here, but just in case
+    if last_error:
+        raise last_error
+    raise RuntimeError("Unexpected error in with_auto_restart")
+
+
+# =============================================================================
+# Private helpers
+# =============================================================================
+
+def _print_start_instructions() -> None:
+    """Print platform-specific start instructions."""
+    system = platform.system()
+
+    if system == "Darwin":
+        print("  open /Applications/CMDOP.app")
+    elif system == "Windows":
+        print("  Start CMDOP from Start Menu")
+        print("  or run: CMDOP.exe")
+    elif system == "Linux":
+        print("  cmdop serve")
+    else:
+        print("  Start CMDOP Desktop application")

cmdop/models/config.py

@@ -16,8 +16,8 @@ class KeepaliveConfig(BaseModel):
 
     model_config = ConfigDict(extra="forbid", frozen=True)
 
-    time_ms: Annotated[int, Field(ge=1000, le=300_000)] = 10_000
-    """Interval between keepalive pings (ms). Default: 10s"""
+    time_ms: Annotated[int, Field(ge=1000, le=300_000)] = 30_000
+    """Interval between keepalive pings (ms). Default: 30s"""
 
     timeout_ms: Annotated[int, Field(ge=500, le=60_000)] = 5_000
     """Timeout waiting for ping response (ms). Default: 5s"""

{cmdop-0.1.28.dist-info → cmdop-0.1.30.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cmdop
-Version: 0.1.28
+Version: 0.1.30
 Summary: Python SDK for CMDOP agent interaction
 Project-URL: Homepage, https://cmdop.com
 Project-URL: Documentation, https://cmdop.com

{cmdop-0.1.28.dist-info → cmdop-0.1.30.dist-info}/RECORD

@@ -1,4 +1,4 @@
-cmdop/__init__.py,sha256=ICgs-pVllaoCC_UzbiGoDalx1ZdVYLvbAXdLmNALLUk,5271
+cmdop/__init__.py,sha256=FCoVmVkm-3kuPc9kyU5mH4tac503r1IoP0kqmqERi7g,5517
 cmdop/client.py,sha256=nTotStZPBfYN3TrHH-OlEJMSVAXskYMQRkocsFmyaBY,14601
 cmdop/config.py,sha256=vpw1aGCyS4NKlZyzVur81Lt06QmN3FnscZji0bypUi0,4398
 cmdop/discovery.py,sha256=HNxSOa5tSuG7ppfFs21XdviW5ucjpRswVPguhX5j8Dg,7479
@@ -150,12 +150,13 @@ cmdop/api/generated/workspaces/workspaces__api__workspaces/__init__.py,sha256=Wo
 cmdop/api/generated/workspaces/workspaces__api__workspaces/client.py,sha256=RcBOR3WCicf5xSjsZApJ9oQ3a0PGpZD6z-2R0IbxRHQ,16547
 cmdop/api/generated/workspaces/workspaces__api__workspaces/models.py,sha256=KCmK-CUuODGIqREu3WBlKKic9SElk7MY3OkD8zNVS78,10230
 cmdop/api/generated/workspaces/workspaces__api__workspaces/sync_client.py,sha256=BKpMmMYzGw6pmDItC_TpJ_mvuI1zmDppXObWncWszE4,16147
-cmdop/helpers/__init__.py,sha256=EGoWhmQojGlwic4oISx7pwFq5WDSfdNh9hhTxzwdkbs,220
+cmdop/helpers/__init__.py,sha256=1kSurulAO8E_uG-E2RK3zGlRCmBLpDmPfuVH8cz7Gpo,543
+cmdop/helpers/desktop.py,sha256=v3E-a54dB6cV7NEFUivM7C0Xko1uEMMpGWfWA-uHxtg,10350
 cmdop/helpers/network_analyzer.py,sha256=ZiTRv39S_kTAppTVbq97DYLExS2WsDLCxf_N4rtnkf0,13025
 cmdop/models/__init__.py,sha256=W6P1oo6JkUAeVEV59HzFT646hXM0pk_obXHfHbX4tAc,1594
 cmdop/models/agent.py,sha256=Z1QDfr1-DTFVl5oPvbH2ZUBLXPHUlitiCRfG7y_OzYg,5495
 cmdop/models/base.py,sha256=1SR1ka5p-rHHkk4k9pPwbraxX_CsTG830CosGNPn1JA,7425
-cmdop/models/config.py,sha256=i3Pc7i57dYqryuIjkigmjlUWpR3lz9Obxwyu5Xa8Lzc,3198
+cmdop/models/config.py,sha256=kBkr4TFBxM07JMBG349D00C_2pzW7RGzxeGAoRCFwZw,3198
 cmdop/models/extract.py,sha256=-HOoAYZ8c7mNNOVOfW3cR6NrhzMvJla5jiGbphsfOBs,2098
 cmdop/models/files.py,sha256=Up96os9fjbDNsVt_wYZKOs3kc-i4uPEOr2KWtItKRYc,3528
 cmdop/models/terminal.py,sha256=g5xcNEa_d3Dvq13QGHRBdh-lkFoN1MU_O1QNmyFM7nI,5135
@@ -198,7 +199,7 @@ cmdop/transport/base.py,sha256=2pkV8i9epgp_21dyReCfX47abRUrnALm0W5BXb-Fuz0,5571
 cmdop/transport/discovery.py,sha256=rcGAuVrR1l6jwcP0dqZxVhX1NsFK7sRHygFMCLmmUbA,10673
 cmdop/transport/local.py,sha256=ob6tWVxSdKwblHSMK8CkgjyuSdQoAeWgy5OAUd5ZNuE,7411
 cmdop/transport/remote.py,sha256=FNVqus9wOv7LlxKarXjLmSyvJiHwhvPbNDOPv1IQkmE,4329
-cmdop-0.1.28.dist-info/METADATA,sha256=DQ-6-awSrNB7dwy_j_7cfj6tsNIAl-zogYNTd3WVJbQ,10563
-cmdop-0.1.28.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-cmdop-0.1.28.dist-info/licenses/LICENSE,sha256=6hyzbI1QVXW6B-XT7PaQ6UG9lns11Y_nnap8uUKGUqo,1062
-cmdop-0.1.28.dist-info/RECORD,,
+cmdop-0.1.30.dist-info/METADATA,sha256=hhryMuocXskH1_EwQsX3Cclay-3n_E_eCJOuPMYGvkI,10563
+cmdop-0.1.30.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+cmdop-0.1.30.dist-info/licenses/LICENSE,sha256=6hyzbI1QVXW6B-XT7PaQ6UG9lns11Y_nnap8uUKGUqo,1062
+cmdop-0.1.30.dist-info/RECORD,,