scitex 2.17.0__py3-none-any.whl → 2.17.4__py3-none-any.whl

scitex/_mcp_tools/dev.py

@@ -0,0 +1,186 @@
+#!/usr/bin/env python3
+# Timestamp: 2026-02-02
+# File: scitex/_mcp_tools/dev.py
+
+"""MCP tool registration for developer utilities."""
+
+from __future__ import annotations
+
+import json
+
+
+def _json(obj) -> str:
+    """Serialize object to JSON string."""
+    return json.dumps(obj, indent=2, default=str)
+
+
+def register_dev_tools(mcp) -> None:
+    """Register developer tools with FastMCP server."""
+
+    @mcp.tool()
+    async def dev_list_versions(
+        packages: list[str] | None = None,
+    ) -> str:
+        """[dev] List versions across the scitex ecosystem.
+
+        Shows version information from multiple sources:
+        - pyproject.toml (local source)
+        - installed package (importlib.metadata)
+        - git tag (latest version tag)
+        - git branch (current branch)
+        - PyPI (remote published version)
+
+        Parameters
+        ----------
+        packages : list[str] | None
+            List of package names to check. If None, checks all ecosystem packages.
+            Available packages: scitex, scitex-cloud, scitex-writer, scitex-dataset,
+            figrecipe, crossref-local, openalex-local, socialia
+
+        Returns
+        -------
+        str
+            JSON with version information for each package.
+        """
+        from scitex._dev._mcp.handlers import list_versions_handler
+
+        result = await list_versions_handler(packages)
+        return _json(result)
+
+    @mcp.tool()
+    async def dev_check_versions(
+        packages: list[str] | None = None,
+    ) -> str:
+        """[dev] Check version consistency across the scitex ecosystem.
+
+        Checks for version mismatches between sources and returns a summary.
+
+        Status values:
+        - ok: All versions consistent
+        - mismatch: Local sources disagree
+        - unreleased: Local > PyPI (ready to release)
+        - outdated: Local < PyPI (should update)
+        - unavailable: Package not found locally
+
+        Parameters
+        ----------
+        packages : list[str] | None
+            List of package names to check. If None, checks all ecosystem packages.
+
+        Returns
+        -------
+        str
+            JSON with detailed version check results and summary.
+        """
+        from scitex._dev._mcp.handlers import check_versions_handler
+
+        result = await check_versions_handler(packages)
+        return _json(result)
+
+    @mcp.tool()
+    async def dev_check_hosts(
+        packages: list[str] | None = None,
+        hosts: list[str] | None = None,
+    ) -> str:
+        """[dev] Check package versions on SSH hosts.
+
+        Connects to configured SSH hosts and checks installed package versions.
+        Hosts are configured in ~/.scitex/dev_config.yaml or via SCITEX_DEV_HOSTS.
+
+        Parameters
+        ----------
+        packages : list[str] | None
+            List of package names to check. If None, checks all ecosystem packages.
+        hosts : list[str] | None
+            List of host names to check. If None, checks all enabled hosts.
+
+        Returns
+        -------
+        str
+            JSON with host -> package -> version mapping.
+        """
+        from scitex._dev._mcp.handlers import check_hosts_handler
+
+        result = await check_hosts_handler(packages, hosts)
+        return _json(result)
+
+    @mcp.tool()
+    async def dev_check_remotes(
+        packages: list[str] | None = None,
+        remotes: list[str] | None = None,
+    ) -> str:
+        """[dev] Check package versions on GitHub remotes.
+
+        Fetches tags and releases from configured GitHub organizations.
+        Remotes are configured in ~/.scitex/dev_config.yaml.
+
+        Parameters
+        ----------
+        packages : list[str] | None
+            List of package names to check. If None, checks all ecosystem packages.
+        remotes : list[str] | None
+            List of remote names to check. If None, checks all enabled remotes.
+
+        Returns
+        -------
+        str
+            JSON with remote -> package -> version mapping.
+        """
+        from scitex._dev._mcp.handlers import check_remotes_handler
+
+        result = await check_remotes_handler(packages, remotes)
+        return _json(result)
+
+    @mcp.tool()
+    async def dev_get_config() -> str:
+        """[dev] Get current developer configuration.
+
+        Returns the configuration from ~/.scitex/dev_config.yaml including:
+        - Packages to track
+        - SSH hosts
+        - GitHub remotes
+        - Branches to track
+
+        Returns
+        -------
+        str
+            JSON with current configuration.
+        """
+        from scitex._dev._mcp.handlers import get_config_handler
+
+        result = await get_config_handler()
+        return _json(result)
+
+    @mcp.tool()
+    async def dev_full_versions(
+        packages: list[str] | None = None,
+        include_hosts: bool = False,
+        include_remotes: bool = True,
+    ) -> str:
+        """[dev] Get comprehensive version data from all sources.
+
+        Combines local, host, and GitHub remote version information.
+
+        Parameters
+        ----------
+        packages : list[str] | None
+            List of package names to check. If None, checks all ecosystem packages.
+        include_hosts : bool
+            Include SSH host version checks (slower, requires SSH access).
+        include_remotes : bool
+            Include GitHub remote version checks.
+
+        Returns
+        -------
+        str
+            JSON with combined version data.
+        """
+        from scitex._dev._mcp.handlers import get_full_versions_handler
+
+        result = await get_full_versions_handler(
+            packages, include_hosts, include_remotes
+        )
+        return _json(result)
+
+
+# EOF

scitex/audio/_audio_check.py

@@ -7,9 +7,75 @@ before attempting to play audio.
 
 from __future__ import annotations
 
+import os
+import shutil
 import subprocess
 
-__all__ = ["check_local_audio_available"]
+__all__ = ["check_local_audio_available", "check_wsl_windows_audio_available"]
+
+
+def check_wsl_windows_audio_available() -> dict:
+    """Check if WSL Windows audio playback is available.
+
+    In WSL, audio can be played via PowerShell's System.Media.SoundPlayer
+    even when PulseAudio is unavailable or SUSPENDED.
+
+    Returns
+    -------
+        dict with keys:
+        - available: bool - True if Windows playback via PowerShell is possible
+        - reason: str - Human-readable explanation
+    """
+    if not os.path.exists("/mnt/c/Windows"):
+        return {"available": False, "reason": "Not running in WSL"}
+
+    if not shutil.which("powershell.exe"):
+        return {"available": False, "reason": "powershell.exe not found in PATH"}
+
+    return {
+        "available": True,
+        "reason": "WSL Windows playback available via PowerShell",
+    }
+
+
+def _try_wsl_fallback(
+    state: str, reason: str, pulseaudio_state: str | None = None
+) -> dict:
+    """Try WSL Windows fallback, return appropriate result dict."""
+    wsl_check = check_wsl_windows_audio_available()
+    if wsl_check["available"]:
+        result = {
+            "available": True,
+            "state": "WSL_WINDOWS",
+            "reason": wsl_check["reason"],
+            "fallback": "windows_powershell",
+        }
+        if pulseaudio_state:
+            result["pulseaudio_state"] = pulseaudio_state
+        return result
+    return {"available": False, "state": state, "reason": reason}
+
+
+def _parse_pulseaudio_state(output: str) -> dict:
+    """Parse PulseAudio sink state from pactl output."""
+    for line in output.strip().split("\n"):
+        parts = line.split("\t")
+        if len(parts) >= 5:
+            state = parts[4]
+            if state == "SUSPENDED":
+                return _try_wsl_fallback(
+                    "SUSPENDED",
+                    "Audio sink SUSPENDED (no active output device)",
+                    pulseaudio_state="SUSPENDED",
+                )
+            if state in ("RUNNING", "IDLE"):
+                return {
+                    "available": True,
+                    "state": state,
+                    "reason": f"Audio sink is {state}",
+                }
+
+    return _try_wsl_fallback("UNKNOWN", "Could not determine sink state")
 
 
 def check_local_audio_available() -> dict:
@@ -18,11 +84,15 @@ def check_local_audio_available() -> dict:
     Checks PulseAudio sink state to determine if audio can actually be heard.
     On NAS or headless servers, the sink is typically SUSPENDED.
 
-    Returns:
+    In WSL environments, also checks for Windows playback fallback via PowerShell.
+
+    Returns
+    -------
         dict with keys:
         - available: bool - True if local audio output is likely to work
         - state: str - 'RUNNING', 'IDLE', 'SUSPENDED', 'NO_SINK', etc.
         - reason: str - Human-readable explanation
+        - fallback: str (optional) - Fallback method if primary unavailable
     """
     try:
         result = subprocess.run(
@@ -32,45 +102,22 @@ def check_local_audio_available() -> dict:
             timeout=5,
         )
         if result.returncode != 0:
-            return {
-                "available": False,
-                "state": "NO_PACTL",
-                "reason": "PulseAudio not available",
-            }
+            return _try_wsl_fallback("NO_PACTL", "PulseAudio not available")
 
         if not result.stdout.strip():
-            return {
-                "available": False,
-                "state": "NO_SINK",
-                "reason": "No audio sinks found",
-            }
+            return _try_wsl_fallback("NO_SINK", "No audio sinks found")
 
-        # Parse sink state (format: id\tname\tmodule\tformat\tstate)
-        for line in result.stdout.strip().split("\n"):
-            parts = line.split("\t")
-            if len(parts) >= 5:
-                state = parts[4]
-                if state == "SUSPENDED":
-                    return {
-                        "available": False,
-                        "state": "SUSPENDED",
-                        "reason": "Audio sink SUSPENDED (no active output device)",
-                    }
-                elif state in ("RUNNING", "IDLE"):
-                    return {
-                        "available": True,
-                        "state": state,
-                        "reason": f"Audio sink is {state}",
-                    }
-
-        return {
-            "available": False,
-            "state": "UNKNOWN",
-            "reason": "Could not determine sink state",
-        }
+        return _parse_pulseaudio_state(result.stdout)
 
     except FileNotFoundError:
-        # No pactl - might be macOS or minimal system, assume available
+        wsl_check = check_wsl_windows_audio_available()
+        if wsl_check["available"]:
+            return {
+                "available": True,
+                "state": "WSL_WINDOWS",
+                "reason": wsl_check["reason"],
+                "fallback": "windows_powershell",
+            }
         return {
             "available": True,
             "state": "NO_PACTL",
@@ -83,11 +130,7 @@ def check_local_audio_available() -> dict:
             "reason": "PulseAudio query timed out",
         }
     except Exception as e:
-        return {
-            "available": False,
-            "state": "ERROR",
-            "reason": str(e),
-        }
+        return {"available": False, "state": "ERROR", "reason": str(e)}
 
 
 # EOF

scitex/cli/capture.py

@@ -406,32 +406,55 @@ def doctor():
 
 
 @mcp.command("list-tools")
-def list_tools():
-    """
-    List available MCP tools
-
-    \b
-    Example:
-      scitex capture mcp list-tools
-    """
+@click.option("-v", "--verbose", count=True, help="-v params, -vv returns")
+def list_tools(verbose):
+    """List available MCP tools for capture."""
     click.secho("Capture MCP Tools", fg="cyan", bold=True)
     click.echo()
+    # (name, desc, params, returns)
     tools = [
-        ("capture_capture_screenshot", "Capture screenshot"),
-        ("capture_capture_window", "Capture specific window"),
-        ("capture_start_monitoring", "Start continuous capture"),
-        ("capture_stop_monitoring", "Stop monitoring"),
-        ("capture_get_monitoring_status", "Get monitoring status"),
-        ("capture_analyze_screenshot", "Analyze screenshot for errors"),
-        ("capture_list_recent_screenshots", "List recent screenshots"),
-        ("capture_clear_cache", "Clear screenshot cache"),
-        ("capture_create_gif", "Create animated GIF"),
-        ("capture_list_sessions", "List monitoring sessions"),
-        ("capture_get_info", "Get monitor/window info"),
-        ("capture_list_windows", "List visible windows"),
+        (
+            "capture_screenshot",
+            "Capture screenshot",
+            "output_path=None, monitor=0",
+            "str",
+        ),
+        (
+            "capture_window",
+            "Capture specific window",
+            "window_id: str, output=None",
+            "str",
+        ),
+        (
+            "start_monitoring",
+            "Start continuous capture",
+            "interval=5.0, monitor=0",
+            "str",
+        ),
+        ("stop_monitoring", "Stop monitoring", "session_id=None", "str"),
+        ("get_monitoring_status", "Get monitoring status", "", "JSON"),
+        (
+            "analyze_screenshot",
+            "Analyze screenshot for errors",
+            "image_path: str",
+            "JSON",
+        ),
+        ("list_recent_screenshots", "List recent screenshots", "limit=10", "JSON"),
+        ("clear_cache", "Clear screenshot cache", "older_than_hours=24", "JSON"),
+        ("create_gif", "Create animated GIF", "session_id: str, output=None", "str"),
+        ("list_sessions", "List monitoring sessions", "", "JSON"),
+        ("get_info", "Get monitor/window info", "", "JSON"),
+        ("list_windows", "List visible windows", "", "JSON"),
     ]
-    for name, desc in tools:
-        click.echo(f"  {name}: {desc}")
+    for name, desc, params, returns in tools:
+        click.secho(f"  capture_{name}", fg="green", bold=True, nl=False)
+        click.echo(f": {desc}")
+        if verbose >= 1 and params:
+            click.echo(f"    params: {params}")
+        if verbose >= 2:
+            click.echo(f"    returns: {returns}")
+        if verbose >= 1:
+            click.echo()
 
 
 @capture.command("list-python-apis")