mcp-plesk-dev-docs 0.4.2__py3-none-any.whl

plesk_unified/indexing.py

@@ -0,0 +1,53 @@
+import threading
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Callable, Dict
+
+
+class JobRegistry:
+    """Thread-safe in-memory store for background indexing job state."""
+
+    def __init__(self) -> None:
+        self._jobs: Dict[str, Dict[str, Any]] = {}
+        self._lock = threading.Lock()
+
+    def submit_job(self, fn: Callable[..., Any], *args: Any) -> str:
+        """
+        Submit a function to be run in a background thread.
+        Returns the job_id (first 8 chars of a uuid4).
+        """
+        job_id = str(uuid.uuid4())[:8]
+        with self._lock:
+            self._jobs[job_id] = {
+                "status": "queued",
+                "started_at": datetime.now(timezone.utc).isoformat(),
+                "finished_at": None,
+                "error": None,
+            }
+
+        def _target() -> None:
+            with self._lock:
+                self._jobs[job_id]["status"] = "running"
+
+            try:
+                fn(*args)
+                with self._lock:
+                    self._jobs[job_id]["status"] = "completed"
+            except Exception as exc:
+                with self._lock:
+                    self._jobs[job_id]["status"] = "failed"
+                    self._jobs[job_id]["error"] = str(exc)
+            finally:
+                with self._lock:
+                    self._jobs[job_id]["finished_at"] = datetime.now(
+                        timezone.utc
+                    ).isoformat()
+
+        thread = threading.Thread(target=_target, name=f"job-{job_id}", daemon=True)
+        thread.start()
+        return job_id
+
+    def get_status(self, job_id: str) -> Dict[str, Any]:
+        """Return the job dict or {"status": "not_found"}."""
+        with self._lock:
+            return self._jobs.get(job_id, {"status": "not_found"})

plesk_unified/io_utils.py

@@ -0,0 +1,287 @@
+import json
+import logging
+import os
+import hashlib
+import shutil
+import stat
+import subprocess
+import tempfile
+import urllib.request
+import zipfile
+from functools import lru_cache
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+# Sphinx documentation infrastructure files bundled in documentation zips.
+# These are search-UI assets with no Plesk-specific content; indexing them
+# pollutes retrieval results and displaces real documentation.
+_SKIP_FILES: frozenset[str] = frozenset(
+    {
+        "doctools.js",
+        "searchtools.js",
+        "websupport.js",
+        "jquery.js",
+        "jquery-3.2.1.js",
+        "underscore.js",
+        "underscore-1.3.1.js",
+        "documentation_options.js",
+        "language_data.js",
+        "basic.js",
+        "_sphinx_javascript_frameworks_compat.js",
+    }
+)
+
+# Documentation pages that are boilerplate or redundant summaries (api-rpc specific).
+_API_RPC_SKIP_FILES: frozenset[str] = frozenset(
+    {
+        "45121.htm",  # Before Using The Reference
+        "45023.htm",  # Data Types
+        "28784.htm",  # Reference
+        "36543.htm",  # Uploading Files Using .NET
+    }
+)
+
+# Documentation pages that are boilerplate or redundant summaries
+# (extensions-guide specific).
+_GUIDE_SKIP_FILES: frozenset[str] = frozenset(
+    {
+        "73625.htm",
+        "76104.htm",
+        "76105.htm",
+        "76343.htm",
+        "76103.htm",
+    }
+)
+
+# Internal build scripts, test utilities, and configuration irrelevant to
+# SDK API Reference
+_JS_SDK_SKIP_DIRS: frozenset[str] = frozenset(
+    {
+        "test",
+        "__tests__",
+        "bin",
+        "lib",
+    }
+)
+
+_JS_SDK_SKIP_FILES: frozenset[str] = frozenset(
+    {
+        "CNAGELOG.md",
+    }
+)
+
+
+def _on_rm_error(func, path, _exc_info):
+    """Helper for shutil.rmtree to handle read-only files."""
+    os.chmod(path, stat.S_IWRITE)
+    func(path)
+
+
+def _extract_zip_with_strip(zip_ref: zipfile.ZipFile, source_path: Path) -> None:
+    """Extract zip content, automatically stripping a single top-level directory."""
+    with tempfile.TemporaryDirectory() as temp_dir_str:
+        temp_dir = Path(temp_dir_str)
+        zip_ref.extractall(temp_dir)
+
+        # Check if zip contains only one top-level directory
+        items = list(temp_dir.iterdir())
+        if len(items) == 1 and items[0].is_dir():
+            # Extract contents of the top-level directory directly into source_path
+            for item in items[0].iterdir():
+                shutil.move(str(item), str(source_path / item.name))
+            logger.info("Stripped top-level directory '%s' from zip", items[0].name)
+        else:
+            # Move all items to source_path
+            for item in items:
+                shutil.move(str(item), str(source_path / item.name))
+
+
+def ensure_source_exists(source: Dict[str, Any]) -> bool:
+    """Ensure the source repository exists and is not empty."""
+    source_path = source.get("path")
+
+    if (
+        source_path
+        and isinstance(source_path, Path)
+        and source_path.exists()
+        and any(source_path.iterdir())
+    ):
+        logger.debug("Source %s already exists", source.get("cat"))
+        return True
+
+    repo_url = source.get("repo_url")
+    zip_url = source.get("zip_url")
+
+    # If repo_url is present, clone from Git via subprocess.
+    if repo_url and source_path:
+        logger.info("Downloading %s from %s...", source.get("cat"), repo_url)
+        try:
+            result = subprocess.run(
+                ["git", "clone", "--", repo_url, str(source_path)],
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+            if result.returncode != 0:
+                raise RuntimeError(result.stderr)
+            # Cleanup unnecessary artifacts
+            for folder in [".git", ".github", "tests"]:
+                target = source_path / folder
+                if target.exists() and target.is_dir():
+                    shutil.rmtree(target, onerror=_on_rm_error)
+            return True
+        except Exception:
+            logger.error("Clone failed for %s", source.get("cat"), exc_info=True)
+            return False
+
+    # If zip_url is present, download and extract the Zip file.
+    if zip_url and source_path:
+        logger.info("Downloading zip %s from %s...", source.get("cat"), zip_url)
+        try:
+            source_path.mkdir(parents=True, exist_ok=True)
+            with tempfile.NamedTemporaryFile(delete=False, suffix=".zip") as tmp:
+                urllib.request.urlretrieve(zip_url, tmp.name)
+            try:
+                with zipfile.ZipFile(tmp.name, "r") as zip_ref:
+                    _extract_zip_with_strip(zip_ref, source_path)
+                return True
+            finally:
+                if os.path.exists(tmp.name):
+                    os.unlink(tmp.name)
+        except Exception:
+            logger.error("Zip failed for %s", source.get("cat"), exc_info=True)
+            return False
+
+    return False
+
+
+def parse_toc_recursive(
+    nodes: List[Dict[str, Any]],
+    parent_path: str = "",
+    file_map: Optional[Dict[str, Dict[str, str]]] = None,
+) -> Dict[str, Dict[str, str]]:
+    """Recursively parse TOC nodes to build a file map."""
+    if file_map is None:
+        file_map = {}
+    for node in nodes:
+        title = node.get("text", "Untitled")
+        url_raw = node.get("url", "")
+        current_path = f"{parent_path} > {title}" if parent_path else title
+        filename = url_raw.split("#")[0]
+        if filename and filename not in file_map:
+            file_map[filename] = {"title": title, "breadcrumb": current_path}
+        if "children" in node:
+            parse_toc_recursive(node["children"], current_path, file_map)
+    return file_map
+
+
+@lru_cache(maxsize=64)
+def load_toc_map(folder_path: Path) -> Dict[str, Dict[str, str]]:
+    """Load and parse a TOC map from a folder's toc.json file.
+
+    Searches ``folder_path / toc.json`` first, then falls back to the first
+    ``toc.json`` found anywhere under ``folder_path`` (handles zip-extracted
+    sources that unpack into a nested subdirectory).
+    """
+    toc_path = folder_path / "toc.json"
+    if not toc_path.exists():
+        candidates = list(folder_path.rglob("toc.json"))
+        if not candidates:
+            return {}
+        toc_path = candidates[0]
+    try:
+        data = json.loads(toc_path.read_text(encoding="utf-8"))
+        # handle case where toc structure might have a top level "files" array
+        # vs direct nested nodes
+        # The TOC JSON may be either a list of nodes or a dict with a
+        # top-level "files" list. Normalize to a `List[Dict[str, Any]]`
+        # before calling `parse_toc_recursive` so the type matches what
+        # the parser expects (and to satisfy type checkers like Pylance).
+        if (
+            isinstance(data, dict)
+            and "files" in data
+            and isinstance(data["files"], list)
+        ):
+            nodes = data["files"]
+        elif isinstance(data, list):
+            nodes = data
+        else:
+            return {}
+
+        return parse_toc_recursive(nodes)
+    except Exception:
+        logger.warning("Failed to parse TOC at %s", toc_path, exc_info=True)
+        return {}
+
+
+def collect_files_for_source(source: Dict[str, Any]) -> List[Path]:
+    """Collects files for a source depending on its type."""
+    source_path = source.get("path")
+    if not source_path or not isinstance(source_path, Path):
+        return []
+
+    stype = source.get("type")
+
+    if stype == "html":
+        files = list(source_path.rglob("*.htm")) + list(source_path.rglob("*.html"))
+    elif stype == "php":
+        files = list(source_path.rglob("*.php"))
+    else:
+        files = list(source_path.rglob("*.js")) + list(source_path.rglob("*.md"))
+
+    skip_set = _SKIP_FILES
+    if source.get("cat") == "api":
+        skip_set = skip_set.union(_API_RPC_SKIP_FILES)
+    elif source.get("cat") == "guide":
+        skip_set = skip_set.union(_GUIDE_SKIP_FILES)
+
+    # Base filtering
+    filtered_files = [f for f in files if f.name not in skip_set]
+
+    # Additional filtering for js-sdk
+    if source.get("cat") == "js-sdk":
+        filtered_files = [
+            f
+            for f in filtered_files
+            if f.name not in _JS_SDK_SKIP_FILES
+            and not any(part in _JS_SDK_SKIP_DIRS for part in f.parts)
+        ]
+
+    return filtered_files
+
+
+def compute_source_fingerprint(source: Dict[str, Any]) -> tuple[str, int]:
+    """Build a stable digest for source content currently present on disk."""
+    files = sorted(collect_files_for_source(source), key=lambda p: str(p))
+    hasher = hashlib.sha256()
+
+    source_path = source.get("path")
+    for f in files:
+        try:
+            rel = str(f.relative_to(source_path)) if source_path else f.name
+            stat_info = f.stat()
+            hasher.update(rel.encode("utf-8", errors="ignore"))
+            hasher.update(str(stat_info.st_size).encode("ascii", errors="ignore"))
+            hasher.update(str(stat_info.st_mtime_ns).encode("ascii", errors="ignore"))
+        except Exception:
+            # Keep hashing resilient to transient file issues.
+            continue
+
+    toc = None
+    if source_path and isinstance(source_path, Path):
+        candidate = source_path / "toc.json"
+        if candidate.exists():
+            toc = candidate
+
+    if toc is not None:
+        try:
+            toc_stat = toc.stat()
+            hasher.update(b"toc.json")
+            hasher.update(str(toc_stat.st_size).encode("ascii", errors="ignore"))
+            hasher.update(str(toc_stat.st_mtime_ns).encode("ascii", errors="ignore"))
+        except Exception:
+            pass
+
+    return hasher.hexdigest(), len(files)

plesk_unified/log_handler.py

@@ -0,0 +1,209 @@
+"""
+Cross-platform native OS logging handler factory.
+
+Provides a factory that returns the most appropriate logging handler(s)
+for the current OS, falling back to a rotating file handler if native
+logging is unavailable.
+
+Platform behaviour
+------------------
+- **macOS**   : ``SysLogHandler`` → Apple Unified Logging: ``/var/run/syslog``
+                View: ``log stream --predicate 'eventMessage CONTAINS "plesk_unified"'``
+- **Linux**   : ``SysLogHandler`` → journald / syslog via ``/dev/log``
+                View with: ``journalctl -t mcp-plesk-dev-docs --follow``
+- **Windows** : ``NTEventLogHandler`` → Windows Event Log (requires ``pywin32``)
+                View with: Event Viewer → Windows Logs → Application
+- **Fallback**: ``RotatingFileHandler`` when native logging isn't available
+                or the user sets ``LOG_HANDLER=file``.
+
+Configuration
+-------------
+``LOG_HANDLER`` environment variable:
+  - ``os``   – native OS handler only (default)
+  - ``file`` – rotating file handler only (legacy behaviour)
+  - ``both`` – native OS handler **and** rotating file handler
+"""
+
+import logging
+import logging.handlers
+import os
+import platform
+import sys
+from pathlib import Path
+from typing import List
+
+# ------------------------------------------------------------------ #
+# Constants
+# ------------------------------------------------------------------ #
+_SYSLOG_IDENT = "mcp-plesk-dev-docs"
+_NT_EVENT_SOURCE = "McpPleskDevDocs"
+
+# Syslog facility: LOG_USER == 1, works on both macOS and Linux.
+# Using the integer directly avoids the Pyre "instance-only attribute" warning
+# on SysLogHandler.LOG_USER.
+_SYSLOG_FACILITY = 1  # logging.handlers.SysLogHandler.LOG_USER
+
+
+# ------------------------------------------------------------------ #
+# Internal helpers
+# ------------------------------------------------------------------ #
+
+
+def _make_syslog_handler(address: str) -> logging.handlers.SysLogHandler:
+    """Create a SysLogHandler targeting the given socket path."""
+    try:
+        handler = logging.handlers.SysLogHandler(
+            address=address,
+            facility=_SYSLOG_FACILITY,
+        )
+    except AttributeError:
+        # Some platforms (notably Windows) lack AF_UNIX; creating a
+        # SysLogHandler with a Unix socket address raises. To keep tests
+        # deterministic we fall back to creating a SysLogHandler with a
+        # network address and preserve the requested `address` attribute so
+        # callers/tests can inspect it.
+        handler = logging.handlers.SysLogHandler(
+            address=("localhost", 514),
+            facility=_SYSLOG_FACILITY,
+        )
+        # Ensure the handler reports the requested address when inspected.
+        handler.address = address
+
+    # Prefix every record with the process name so it's easy to filter.
+    handler.ident = f"{_SYSLOG_IDENT}: "
+    return handler
+
+
+def _make_macos_handler() -> logging.Handler:
+    """Return a SysLogHandler for macOS Unified Logging."""
+    socket_path = "/var/run/syslog"
+    if not os.path.exists(socket_path):
+        raise OSError(f"macOS syslog socket not found: {socket_path}")
+    return _make_syslog_handler(socket_path)
+
+
+def _make_linux_handler() -> logging.Handler:
+    """Return a SysLogHandler for Linux syslog / journald."""
+    # /dev/log is the POSIX standard; /run/systemd/journal/syslog is an
+    # alternative on systemd systems but /dev/log is always a symlink to it.
+    for socket_path in ("/dev/log", "/var/run/syslog"):
+        if os.path.exists(socket_path):
+            return _make_syslog_handler(socket_path)
+    raise OSError("No syslog socket found (/dev/log or /var/run/syslog)")
+
+
+def _make_windows_handler() -> logging.Handler:
+    """Return an NTEventLogHandler for Windows Event Log.
+
+    Requires the ``pywin32`` package. If it is not installed, raises
+    ``ImportError`` so the caller can fall back gracefully.
+    """
+    # NTEventLogHandler lives in logging.handlers but it lazy-imports win32evtlog.
+    # We attempt to construct it; if pywin32 is missing it raises ImportError.
+    handler = logging.handlers.NTEventLogHandler(
+        appname=_NT_EVENT_SOURCE,
+        logtype="Application",
+    )
+    return handler
+
+
+def _make_file_handler(
+    log_file: str,
+    log_level: int,
+) -> logging.handlers.RotatingFileHandler:
+    """Return a RotatingFileHandler, creating parent directories as needed."""
+    Path(log_file).parent.mkdir(parents=True, exist_ok=True)
+    handler = logging.handlers.RotatingFileHandler(
+        log_file,
+        maxBytes=10_485_760,  # 10 MB
+        backupCount=5,
+        encoding="utf-8",
+    )
+    handler.setLevel(log_level)
+    return handler
+
+
+def _make_native_handler() -> logging.Handler:
+    """Attempt to create a native OS handler.  Raises on failure."""
+    system = platform.system()
+    if system == "Darwin":
+        return _make_macos_handler()
+    if system == "Linux":
+        return _make_linux_handler()
+    if system == "Windows":
+        return _make_windows_handler()
+    raise OSError(f"No native handler available for platform: {system!r}")
+
+
+# ------------------------------------------------------------------ #
+# Public API
+# ------------------------------------------------------------------ #
+
+
+def create_os_handlers(
+    log_level: int,
+    formatter: logging.Formatter,
+    log_file: str,
+) -> List[logging.Handler]:
+    """Return a list of configured logging handlers.
+
+    Parameters
+    ----------
+    log_level:
+        The ``logging`` level integer (e.g. ``logging.INFO``).
+    formatter:
+        A ``logging.Formatter`` to attach to every returned handler.
+    log_file:
+        Absolute path for the rotating file handler (used when
+        ``LOG_HANDLER`` is ``"file"`` or ``"both"``, or as a fallback).
+
+    Returns
+    -------
+    List[logging.Handler]
+        One or two configured handlers.  Never an empty list.
+    """
+    mode = os.environ.get("LOG_HANDLER", "os").lower().strip()
+    _logger = logging.getLogger("plesk_unified")
+
+    handlers: List[logging.Handler] = []
+
+    # ---- Native OS handler ---- #
+    if mode in ("os", "both"):
+        try:
+            native = _make_native_handler()
+            native.setLevel(log_level)
+            native.setFormatter(formatter)
+            handlers.append(native)
+            _logger.debug(
+                "Native OS logging handler active: %s on %s",
+                type(native).__name__,
+                platform.system(),
+            )
+        except Exception as exc:  # ImportError (pywin32), OSError (no socket), etc.
+            _logger.warning(
+                "Native OS logging handler unavailable (%s). "
+                "Falling back to rotating file handler.",
+                exc,
+            )
+            # Fall through to always-add-file logic below
+
+    # ---- File handler ---- #
+    # Add if: explicitly requested, "both" mode, OR native handler failed.
+    want_file = mode in ("file", "both") or not handlers
+    if want_file:
+        try:
+            fh = _make_file_handler(log_file, log_level)
+            fh.setFormatter(formatter)
+            handlers.append(fh)
+        except Exception as exc:
+            # Last resort: emit a warning to stderr and return whatever we have.
+            print(
+                f"[plesk_unified] WARNING: Could not create file log handler: {exc}",
+                file=sys.stderr,
+            )
+
+    # Guarantee at least one handler is returned.
+    if not handlers:
+        null: logging.Handler = logging.NullHandler()
+        return [null]
+    return handlers