delimit-cli 4.5.1 → 4.5.3

package/gateway/ai/remote_resolve.py

@@ -0,0 +1,422 @@
+"""Remote-input resolution helpers for MCP tools (LED-1237).
+
+Tools like delimit_repo_analyze and delimit_lint historically only
+accepted local filesystem paths. When a multi-model deliberation panel
+emits ``[TOOL: delimit_repo_analyze target="calcom/cal.com"]`` the
+target was resolved against the cwd and silently returned an empty
+analysis (total_files=0).
+
+This module adds **additive** remote-input handling:
+
+* ``resolve_repo_target(target)`` — context manager that accepts either
+  a local path, a ``<owner>/<repo>`` shorthand, or a full
+  https/ssh GitHub URL, and yields ``(local_path, metadata)``.
+
+* ``resolve_spec_input(spec)`` — context manager that accepts either a
+  local path or an http(s) URL, fetches the URL into a tempfile with
+  the right extension, and yields ``(local_path, metadata)``.
+
+Both helpers are no-ops on local input (passthrough). All cleanup is
+handled automatically. Network/clone failures raise
+``RemoteResolveError`` which callers should convert into a clean
+``{"error": "...", ...}`` response.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import ipaddress
+import logging
+import os
+import re
+import shutil
+import socket
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import Any, Dict, Iterator, Optional, Tuple
+from urllib.parse import urlparse
+
+logger = logging.getLogger("delimit.ai.remote_resolve")
+
+# ─── Constants ───────────────────────────────────────────────────────────
+
+GIT_CLONE_TIMEOUT_S = 120
+HTTP_FETCH_TIMEOUT_S = 60
+HTTP_FETCH_MAX_BYTES = 10 * 1024 * 1024  # 10 MB
+
+# <owner>/<repo> regex: each segment is a non-empty token without
+# whitespace, slashes (other than the single separator), or path
+# traversal. We deliberately keep this conservative — anything fancy
+# falls back to local-path semantics.
+_OWNER_REPO_RE = re.compile(r"^([A-Za-z0-9][A-Za-z0-9._-]*)/([A-Za-z0-9][A-Za-z0-9._-]*)$")
+
+_GITHUB_URL_PREFIXES = (
+    "https://github.com/",
+    "http://github.com/",
+    "git@github.com:",
+    "ssh://git@github.com/",
+)
+
+
+# ─── Exceptions ──────────────────────────────────────────────────────────
+
+
+class RemoteResolveError(Exception):
+    """Raised when a remote target cannot be resolved.
+
+    Carries an ``error`` code and a human-readable detail. Callers
+    should translate this into a structured response dict — never let
+    it bubble up as a stack trace into an MCP response.
+    """
+
+    def __init__(self, error: str, detail: str, target: Optional[str] = None) -> None:
+        super().__init__(detail)
+        self.error = error
+        self.detail = detail
+        self.target = target
+
+    def to_dict(self) -> Dict[str, Any]:
+        out: Dict[str, Any] = {"error": self.error, "detail": self.detail}
+        if self.target is not None:
+            out["target"] = self.target
+        return out
+
+
+# ─── Repo target classification ──────────────────────────────────────────
+
+
+def _is_github_url(target: str) -> bool:
+    return any(target.startswith(p) for p in _GITHUB_URL_PREFIXES)
+
+
+def _normalize_github_url(target: str) -> str:
+    """Convert any accepted GitHub URL form to an https clone URL.
+
+    Handles ``git@github.com:owner/repo(.git)`` and
+    ``ssh://git@github.com/owner/repo(.git)`` plus pre-formed
+    ``https://github.com/owner/repo``.
+    """
+    if target.startswith("git@github.com:"):
+        path = target[len("git@github.com:"):]
+        return "https://github.com/" + path.rstrip("/")
+    if target.startswith("ssh://git@github.com/"):
+        path = target[len("ssh://git@github.com/"):]
+        return "https://github.com/" + path.rstrip("/")
+    if target.startswith("http://github.com/"):
+        return "https://" + target[len("http://"):]
+    return target.rstrip("/")
+
+
+def _looks_like_owner_repo(target: str) -> bool:
+    """Detect ``owner/repo`` shorthand.
+
+    Required:
+    * exactly one '/' separator
+    * both halves non-empty and match a conservative slug pattern
+    * no path traversal ('..'); does not start with '/' or '.'
+    * the literal ``./<owner>/<repo>`` does not exist on disk
+      (backwards-compat guard so a real local subdir wins)
+    """
+    if not target or target.startswith(("/", ".")):
+        return False
+    if ".." in target.split("/"):
+        return False
+    if not _OWNER_REPO_RE.match(target):
+        return False
+    if Path(target).exists():
+        # A real local dir/file with this name exists — treat as local.
+        return False
+    return True
+
+
+def classify_repo_target(target: str) -> str:
+    """Return one of: ``"github_url"``, ``"owner_repo"``, ``"local"``.
+
+    Pure function, no I/O beyond a single ``Path.exists`` check for the
+    backwards-compat guard. Exposed for tests.
+    """
+    if _is_github_url(target):
+        return "github_url"
+    if _looks_like_owner_repo(target):
+        return "owner_repo"
+    return "local"
+
+
+# ─── Git clone ───────────────────────────────────────────────────────────
+
+
+def _git_clone_shallow(url: str, dest: str) -> None:
+    """Run ``git clone --depth 1 <url> <dest>``.
+
+    Raises ``RemoteResolveError`` on failure (non-zero exit, timeout, or
+    git binary missing).
+    """
+    try:
+        proc = subprocess.run(
+            ["git", "clone", "--depth", "1", url, dest],
+            capture_output=True,
+            text=True,
+            timeout=GIT_CLONE_TIMEOUT_S,
+        )
+    except FileNotFoundError as e:
+        raise RemoteResolveError(
+            "clone_failed",
+            f"git binary not found: {e}",
+            target=url,
+        ) from e
+    except subprocess.TimeoutExpired as e:
+        raise RemoteResolveError(
+            "clone_failed",
+            f"git clone timed out after {GIT_CLONE_TIMEOUT_S}s",
+            target=url,
+        ) from e
+    except Exception as e:  # pragma: no cover - defensive
+        raise RemoteResolveError(
+            "clone_failed",
+            f"git clone failed: {e}",
+            target=url,
+        ) from e
+
+    if proc.returncode != 0:
+        # stderr tends to carry the useful "Repository not found" /
+        # "Authentication failed" message. Trim it so we don't dump
+        # huge output into MCP responses.
+        stderr = (proc.stderr or "").strip()
+        if len(stderr) > 500:
+            stderr = stderr[:500] + "..."
+        raise RemoteResolveError(
+            "clone_failed",
+            stderr or f"git clone exited with code {proc.returncode}",
+            target=url,
+        )
+
+
+@contextlib.contextmanager
+def resolve_repo_target(target: str) -> Iterator[Tuple[str, Dict[str, Any]]]:
+    """Resolve a repo target to a local path.
+
+    Yields ``(path, metadata)``. Metadata always includes
+    ``resolved_from`` (one of ``"local"``, ``"remote_clone"``) and may
+    include ``upstream_url`` for remote clones.
+
+    Cleanup of any temporary clone happens automatically when the
+    ``with`` block exits, even on exception inside the block.
+
+    Raises ``RemoteResolveError`` if the input cannot be resolved
+    (clone failure, malformed URL). Local-path targets always succeed
+    here — the existence check stays the responsibility of the
+    downstream backend so that ``analyze("nonexistent/")`` keeps its
+    pre-existing behavior.
+    """
+    kind = classify_repo_target(target)
+
+    if kind == "local":
+        yield target, {"resolved_from": "local"}
+        return
+
+    # Remote: normalize to an https URL.
+    if kind == "github_url":
+        url = _normalize_github_url(target)
+    else:  # owner_repo
+        url = f"https://github.com/{target}"
+
+    tmp = tempfile.mkdtemp(prefix="delimit-repo-")
+    # mkdtemp creates the dir; git clone refuses to clone into an
+    # existing non-empty dir, so we point it at a child path.
+    clone_dir = os.path.join(tmp, "repo")
+    try:
+        _git_clone_shallow(url, clone_dir)
+        meta: Dict[str, Any] = {
+            "resolved_from": "remote_clone",
+            "upstream_url": url,
+        }
+        yield clone_dir, meta
+    finally:
+        shutil.rmtree(tmp, ignore_errors=True)
+
+
+# ─── Spec (URL) input resolution ─────────────────────────────────────────
+
+
+_ALLOWED_SPEC_SCHEMES = ("http", "https")
+
+
+def _classify_spec_input(spec: str) -> str:
+    """Return ``"url"`` or ``"local"``.
+
+    Anything starting with ``http://`` or ``https://`` is a URL.
+    Everything else is a local path. Unknown schemes (file://, ftp://,
+    javascript:) are rejected up front — but only if they actually look
+    like a URL, otherwise a local path beginning with ``foo:`` would
+    misclassify on Windows-style drives etc. We're strict: any
+    ``<scheme>://`` prefix that isn't http(s) is rejected.
+    """
+    if spec.startswith(("http://", "https://")):
+        return "url"
+    # Reject other URL-ish schemes outright.
+    m = re.match(r"^([a-zA-Z][a-zA-Z0-9+\-.]*)://", spec)
+    if m:
+        raise RemoteResolveError(
+            "invalid_scheme",
+            f"only http(s) URLs are accepted; got scheme '{m.group(1)}'",
+            target=spec,
+        )
+    # javascript: / data: — no '//' after the colon, treat as local
+    # path candidate (will fail downstream if invalid).
+    return "local"
+
+
+def _ensure_public_host(url: str) -> None:
+    """SSRF guard: reject URLs that resolve to private/loopback IPs.
+
+    Resolves the hostname and checks the resulting IP against the
+    standard private/loopback/link-local/reserved ranges. Raises
+    ``RemoteResolveError`` on any disallowed host.
+    """
+    parsed = urlparse(url)
+    host = parsed.hostname
+    if not host:
+        raise RemoteResolveError(
+            "invalid_url",
+            "URL is missing a hostname",
+            target=url,
+        )
+    try:
+        ip_str = socket.gethostbyname(host)
+    except OSError as e:
+        raise RemoteResolveError(
+            "fetch_failed",
+            f"DNS resolution failed for {host}: {e}",
+            target=url,
+        ) from e
+    try:
+        ip = ipaddress.ip_address(ip_str)
+    except ValueError as e:  # pragma: no cover - defensive
+        raise RemoteResolveError(
+            "fetch_failed",
+            f"could not parse resolved IP {ip_str}: {e}",
+            target=url,
+        ) from e
+    if (
+        ip.is_private
+        or ip.is_loopback
+        or ip.is_link_local
+        or ip.is_reserved
+        or ip.is_multicast
+        or ip.is_unspecified
+    ):
+        raise RemoteResolveError(
+            "blocked_host",
+            f"refusing to fetch from non-public host {host} ({ip_str})",
+            target=url,
+        )
+
+
+def _spec_extension_for(url: str, content_type: str) -> str:
+    """Pick a tempfile extension based on URL or response Content-Type."""
+    parsed = urlparse(url)
+    path = parsed.path.lower()
+    for ext in (".yaml", ".yml", ".json"):
+        if path.endswith(ext):
+            return ext
+    ct = (content_type or "").lower()
+    if "yaml" in ct or "yml" in ct:
+        return ".yaml"
+    if "json" in ct:
+        return ".json"
+    # Fall back: many OpenAPI specs are served with text/plain — use
+    # .json because the loader auto-detects, and json parsers fail
+    # fast and clean on yaml.
+    return ".json"
+
+
+def _http_fetch(url: str) -> Tuple[bytes, str]:
+    """Fetch ``url`` with size/timeout caps. Returns (body, content_type).
+
+    Raises ``RemoteResolveError`` on any failure (network, timeout,
+    oversize body, non-2xx status).
+    """
+    # Lazy import so test envs without urllib quirks don't choke at
+    # module import time.
+    from urllib.error import HTTPError, URLError
+    from urllib.request import Request, urlopen
+
+    req = Request(url, headers={"User-Agent": "delimit-gateway-remote-resolve/1"})
+    try:
+        with urlopen(req, timeout=HTTP_FETCH_TIMEOUT_S) as resp:
+            content_type = resp.headers.get("Content-Type", "")
+            # Read up to MAX+1 to detect oversize.
+            body = resp.read(HTTP_FETCH_MAX_BYTES + 1)
+    except HTTPError as e:
+        raise RemoteResolveError(
+            "fetch_failed",
+            f"HTTP {e.code}: {e.reason}",
+            target=url,
+        ) from e
+    except URLError as e:
+        raise RemoteResolveError(
+            "fetch_failed",
+            f"network error: {e.reason}",
+            target=url,
+        ) from e
+    except Exception as e:
+        raise RemoteResolveError(
+            "fetch_failed",
+            f"fetch failed: {e}",
+            target=url,
+        ) from e
+
+    if len(body) > HTTP_FETCH_MAX_BYTES:
+        raise RemoteResolveError(
+            "fetch_failed",
+            f"response body exceeds {HTTP_FETCH_MAX_BYTES} bytes",
+            target=url,
+        )
+    return body, content_type
+
+
+@contextlib.contextmanager
+def resolve_spec_input(spec: str) -> Iterator[Tuple[str, Dict[str, Any]]]:
+    """Resolve a spec input (local path or URL) to a local path.
+
+    Yields ``(path, metadata)``. Metadata always includes
+    ``resolved_from`` (``"local"`` or ``"url"``) and, for URLs,
+    ``upstream_url`` and ``content_type``.
+
+    Tempfiles are cleaned up automatically when the ``with`` block
+    exits.
+    """
+    kind = _classify_spec_input(spec)
+
+    if kind == "local":
+        yield spec, {"resolved_from": "local"}
+        return
+
+    # URL path: SSRF guard, fetch, write to tempfile.
+    _ensure_public_host(spec)
+    body, content_type = _http_fetch(spec)
+    ext = _spec_extension_for(spec, content_type)
+    fd, tmp_path = tempfile.mkstemp(prefix="delimit-spec-", suffix=ext)
+    try:
+        with os.fdopen(fd, "wb") as f:
+            f.write(body)
+        meta: Dict[str, Any] = {
+            "resolved_from": "url",
+            "upstream_url": spec,
+            "content_type": content_type,
+        }
+        yield tmp_path, meta
+    finally:
+        try:
+            os.unlink(tmp_path)
+        except OSError:
+            pass
+
+
+__all__ = [
+    "RemoteResolveError",
+    "classify_repo_target",
+    "resolve_repo_target",
+    "resolve_spec_input",
+]