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

scitex/_dev/_versions.py

@@ -0,0 +1,272 @@
+#!/usr/bin/env python3
+# Timestamp: 2026-02-02
+# File: scitex/_dev/_versions.py
+
+"""Core version checking logic for the scitex ecosystem."""
+
+from __future__ import annotations
+
+import re
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from ._ecosystem import ECOSYSTEM, get_all_packages, get_local_path
+
+
+def get_version_from_toml(path: Path) -> str | None:
+    """Read version from pyproject.toml."""
+    toml_path = path / "pyproject.toml"
+    if not toml_path.exists():
+        return None
+
+    try:
+        # Python 3.11+
+        import tomllib
+
+        with open(toml_path, "rb") as f:
+            data = tomllib.load(f)
+    except ImportError:
+        try:
+            import tomli
+
+            with open(toml_path, "rb") as f:
+                data = tomli.load(f)
+        except ImportError:
+            # Fallback: regex parse
+            content = toml_path.read_text()
+            match = re.search(
+                r'^version\s*=\s*["\']([^"\']+)["\']', content, re.MULTILINE
+            )
+            return match.group(1) if match else None
+
+    return data.get("project", {}).get("version")
+
+
+def get_version_installed(package: str) -> str | None:
+    """Get version from importlib.metadata."""
+    try:
+        from importlib.metadata import version
+
+        return version(package)
+    except Exception:
+        return None
+
+
+def get_git_latest_tag(path: Path) -> str | None:
+    """Get latest git tag (version tags only)."""
+    if not path.exists():
+        return None
+
+    try:
+        result = subprocess.run(
+            ["git", "describe", "--tags", "--abbrev=0", "--match", "v*"],
+            cwd=path,
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        if result.returncode == 0:
+            return result.stdout.strip()
+    except Exception:
+        pass
+
+    # Fallback: list all tags
+    try:
+        result = subprocess.run(
+            ["git", "tag", "-l", "v*", "--sort=-v:refname"],
+            cwd=path,
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        if result.returncode == 0 and result.stdout.strip():
+            return result.stdout.strip().split("\n")[0]
+    except Exception:
+        pass
+
+    return None
+
+
+def get_git_branch(path: Path) -> str | None:
+    """Get current git branch."""
+    if not path.exists():
+        return None
+
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+            cwd=path,
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        if result.returncode == 0:
+            return result.stdout.strip()
+    except Exception:
+        pass
+
+    return None
+
+
+def get_pypi_version(package: str) -> str | None:
+    """Fetch latest version from PyPI API."""
+    try:
+        import urllib.request
+
+        url = f"https://pypi.org/pypi/{package}/json"
+        with urllib.request.urlopen(url, timeout=5) as response:
+            import json
+
+            data = json.loads(response.read().decode())
+            return data.get("info", {}).get("version")
+    except Exception:
+        return None
+
+
+def _normalize_version(v: str | None) -> str | None:
+    """Normalize version string (strip v prefix)."""
+    if v is None:
+        return None
+    return v.lstrip("v")
+
+
+def _compare_versions(v1: str | None, v2: str | None) -> int:
+    """Compare two version strings. Returns -1, 0, or 1."""
+    if v1 is None or v2 is None:
+        return 0
+
+    from packaging.version import Version
+
+    try:
+        ver1 = Version(_normalize_version(v1))
+        ver2 = Version(_normalize_version(v2))
+        if ver1 < ver2:
+            return -1
+        if ver1 > ver2:
+            return 1
+        return 0
+    except Exception:
+        # Fallback: string comparison
+        return 0
+
+
+def _determine_status(info: dict[str, Any]) -> tuple[str, list[str]]:
+    """Determine version status and issues."""
+    issues = []
+
+    toml_ver = info.get("local", {}).get("pyproject_toml")
+    installed_ver = info.get("local", {}).get("installed")
+    tag_ver = _normalize_version(info.get("git", {}).get("latest_tag"))
+    pypi_ver = info.get("remote", {}).get("pypi")
+
+    # Check local consistency
+    if toml_ver and installed_ver and toml_ver != installed_ver:
+        issues.append(f"pyproject.toml ({toml_ver}) != installed ({installed_ver})")
+
+    # Check if toml matches tag
+    if toml_ver and tag_ver and toml_ver != tag_ver:
+        issues.append(f"pyproject.toml ({toml_ver}) != git tag ({tag_ver})")
+
+    # Check pypi status
+    if toml_ver and pypi_ver:
+        cmp = _compare_versions(toml_ver, pypi_ver)
+        if cmp > 0:
+            issues.append(f"local ({toml_ver}) > pypi ({pypi_ver}) - ready to release")
+            return "unreleased", issues
+        if cmp < 0:
+            issues.append(f"local ({toml_ver}) < pypi ({pypi_ver}) - outdated")
+            return "outdated", issues
+
+    if issues:
+        return "mismatch", issues
+
+    if not toml_ver:
+        return "unavailable", ["package not found locally"]
+
+    return "ok", []
+
+
+def list_versions(packages: list[str] | None = None) -> dict[str, Any]:
+    """List versions for all ecosystem packages.
+
+    Parameters
+    ----------
+    packages : list[str] | None
+        List of package names to check. If None, checks all ecosystem packages.
+
+    Returns
+    -------
+    dict
+        Version information for each package.
+    """
+    if packages is None:
+        packages = get_all_packages()
+
+    result = {}
+    for pkg in packages:
+        if pkg not in ECOSYSTEM:
+            result[pkg] = {"status": "unknown", "issues": [f"'{pkg}' not in ecosystem"]}
+            continue
+
+        info: dict[str, Any] = {"local": {}, "git": {}, "remote": {}}
+        local_path = get_local_path(pkg)
+        pypi_name = ECOSYSTEM[pkg].get("pypi_name", pkg)
+
+        # Local sources
+        if local_path and local_path.exists():
+            info["local"]["pyproject_toml"] = get_version_from_toml(local_path)
+        info["local"]["installed"] = get_version_installed(pypi_name)
+
+        # Git sources
+        if local_path and local_path.exists():
+            info["git"]["latest_tag"] = get_git_latest_tag(local_path)
+            info["git"]["branch"] = get_git_branch(local_path)
+
+        # Remote sources
+        info["remote"]["pypi"] = get_pypi_version(pypi_name)
+
+        # Determine status
+        status, issues = _determine_status(info)
+        info["status"] = status
+        info["issues"] = issues
+
+        result[pkg] = info
+
+    return result
+
+
+def check_versions(packages: list[str] | None = None) -> dict[str, Any]:
+    """Check version consistency and return detailed status.
+
+    Parameters
+    ----------
+    packages : list[str] | None
+        List of package names to check. If None, checks all ecosystem packages.
+
+    Returns
+    -------
+    dict
+        Detailed version check results with overall summary.
+    """
+    versions = list_versions(packages)
+
+    summary = {
+        "total": len(versions),
+        "ok": 0,
+        "mismatch": 0,
+        "unreleased": 0,
+        "outdated": 0,
+        "unavailable": 0,
+        "unknown": 0,
+    }
+
+    for _pkg, info in versions.items():
+        status = info.get("status", "unknown")
+        if status in summary:
+            summary[status] += 1
+
+    return {"packages": versions, "summary": summary}
+
+
+# EOF

scitex/_mcp_tools/__init__.py

@@ -9,6 +9,7 @@ from .audio import register_audio_tools
 from .canvas import register_canvas_tools
 from .capture import register_capture_tools
 from .dataset import register_dataset_tools
+from .dev import register_dev_tools
 from .diagram import register_diagram_tools
 from .introspect import register_introspect_tools
 from .plt import register_plt_tools
@@ -29,6 +30,7 @@ def register_all_tools(mcp) -> None:
     register_canvas_tools(mcp)
     register_capture_tools(mcp)
     register_dataset_tools(mcp)
+    register_dev_tools(mcp)
     register_diagram_tools(mcp)
     register_introspect_tools(mcp)
     register_plt_tools(mcp)

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