morphsdk 0.2.5__py3-none-any.whl

morphsdk/_providers/code_storage_http.py

@@ -0,0 +1,104 @@
+"""HTTP-backed :class:`RemoteCommands` for the Morph code-storage service.
+
+Translates grep/read/list into POST requests against the code-search endpoints
+so the WarpGrep agent can search GitHub repos indexed by Morph.
+
+Wire contract (must match the TypeScript ``createCodeStorageHttpCommands``):
+
+* ``POST {base_url}/api/code-search/{repo_id}/grep``  body ``{pattern, path, glob, branch}``
+* ``POST {base_url}/api/code-search/{repo_id}/read``  body ``{path, start, end, branch}``
+* ``POST {base_url}/api/code-search/{repo_id}/list``  body ``{path, maxDepth, branch}``
+
+Each endpoint returns ``{"stdout": "..."}`` on success.  Non-2xx responses are
+returned as ``"Error: ..."`` strings (so the agent handles them gracefully); a
+``{"error": ...}`` body on a 2xx response raises.
+"""
+
+from __future__ import annotations
+
+from urllib.parse import quote
+
+import httpx
+
+from .remote import RemoteCommands
+
+
+class CodeStorageHttpConfig:
+    """Connection config for the code-search HTTP backend."""
+
+    def __init__(self, *, base_url: str, repo_id: str, branch: str) -> None:
+        self.base_url = base_url
+        self.repo_id = repo_id
+        self.branch = branch
+
+
+async def _post(
+    client: httpx.AsyncClient,
+    url: str,
+    body: dict[str, object],
+    op: str,
+) -> str:
+    res = await client.post(url, json=body, headers={"Content-Type": "application/json"})
+    if not res.is_success:
+        try:
+            text = res.text
+        except Exception:  # noqa: BLE001
+            text = res.reason_phrase
+        # Return errors as content (not raised) so the agent can recover.
+        try:
+            parsed = res.json()
+            if isinstance(parsed, dict) and parsed.get("error"):
+                return f"Error: {parsed['error']}"
+        except Exception:  # noqa: BLE001 - not JSON, fall through
+            pass
+        return f"Error: {op} failed ({res.status_code}): {text}"
+
+    data = res.json()
+    if isinstance(data, dict) and data.get("error"):
+        raise RuntimeError(str(data["error"]))
+    return str(data["stdout"])
+
+
+def create_code_storage_http_commands(
+    config: CodeStorageHttpConfig,
+    *,
+    client: httpx.AsyncClient | None = None,
+) -> RemoteCommands:
+    """Build a :class:`RemoteCommands` bundle backed by the code-search HTTP API.
+
+    Pass an existing ``httpx.AsyncClient`` to reuse a connection pool; otherwise a
+    short-lived client is created per call.
+    """
+    base_url = config.base_url
+    branch = config.branch
+    encoded_repo_id = quote(config.repo_id, safe="")
+    prefix = f"{base_url}/api/code-search/{encoded_repo_id}"
+
+    async def _call(url: str, body: dict[str, object], op: str) -> str:
+        if client is not None:
+            return await _post(client, url, body, op)
+        async with httpx.AsyncClient() as owned:
+            return await _post(owned, url, body, op)
+
+    async def grep(pattern: str, path: str, glob: str | None) -> str:
+        return await _call(
+            f"{prefix}/grep",
+            {"pattern": pattern, "path": path, "glob": glob, "branch": branch},
+            "grep",
+        )
+
+    async def read(path: str, start: int, end: int) -> str:
+        return await _call(
+            f"{prefix}/read",
+            {"path": path, "start": start, "end": end, "branch": branch},
+            "read",
+        )
+
+    async def list_dir(path: str, max_depth: int) -> str:
+        return await _call(
+            f"{prefix}/list",
+            {"path": path, "maxDepth": max_depth, "branch": branch},
+            "list",
+        )
+
+    return RemoteCommands(grep=grep, read=read, list_dir=list_dir)

morphsdk/_providers/local.py

@@ -0,0 +1,270 @@
+"""Local ripgrep-backed WarpGrep provider.
+
+Faithful port of the TypeScript ``LocalRipgrepProvider``: it shells out to
+``rg`` for grep, walks the tree for ``list_directory``, and reads files with
+1-indexed inclusive line ranges.  There is intentionally **no** Python-native
+search fallback -- the TS does not have one either; when ``rg`` is unavailable
+it returns a graceful, agent-readable error.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import math
+import os
+import re
+import shutil
+import subprocess
+import time
+from dataclasses import dataclass
+
+from morphsdk._constants import (
+    DEFAULT_EXCLUDES,
+    WARP_GREP_MAX_LIST_DEPTH,
+    WARP_GREP_MAX_OUTPUT_LINES,
+    WARP_GREP_MAX_READ_LINES,
+)
+
+from ._filter import (
+    is_textual_file,
+    resolve_under_repo,
+    should_skip,
+    to_repo_relative,
+)
+from .base import GrepResult, ListDirectoryEntry, ReadResult, WarpGrepProvider
+
+# Directory walks abort after this many milliseconds (mirrors LIST_TIMEOUT_MS).
+_LIST_TIMEOUT_MS = 2_000
+
+_RIPGREP_NOT_AVAILABLE = (
+    "[RIPGREP NOT AVAILABLE] ripgrep (rg) is required but failed to execute. "
+    "Please install it:\n"
+    "  • macOS: brew install ripgrep\n"
+    "  • Ubuntu/Debian: apt install ripgrep\n"
+    "  • Windows: choco install ripgrep\n"
+    "  • Or visit: https://github.com/BurntSushi/ripgrep#installation"
+)
+
+
+@dataclass
+class _ExecResult:
+    stdout: str
+    stderr: str
+    exit_code: int
+
+
+def _run_ripgrep(args: list[str], cwd: str) -> _ExecResult:
+    """Invoke ``rg`` synchronously. Returns ``exit_code == -1`` if it cannot spawn."""
+    rg = shutil.which("rg")
+    if rg is None:
+        return _ExecResult(stdout="", stderr="ripgrep (rg) not found on PATH.", exit_code=-1)
+    try:
+        proc = subprocess.run(
+            [rg, *args],
+            cwd=cwd,
+            stdin=subprocess.DEVNULL,
+            capture_output=True,
+            text=True,
+        )
+    except OSError as err:  # pragma: no cover - spawn failure is environment-specific
+        return _ExecResult(stdout="", stderr=f"Failed to spawn ripgrep: {err}", exit_code=-1)
+    return _ExecResult(stdout=proc.stdout, stderr=proc.stderr, exit_code=proc.returncode)
+
+
+def _truncate(lines: list[str], limit: int, unit: str) -> list[str]:
+    """Truncate *lines* to *limit*, appending a marker line when it overflows."""
+    if len(lines) <= limit:
+        return lines
+    truncated = lines[:limit]
+    truncated.append(f"... (output truncated at {limit} of {len(lines)} {unit})")
+    return truncated
+
+
+class LocalRipgrepProvider(WarpGrepProvider):
+    """Searches a local checkout via ``rg`` and direct filesystem access."""
+
+    def __init__(
+        self,
+        repo_root: str,
+        excludes: list[str] | None = None,
+        *,
+        allow_names: list[str] | None = None,
+    ) -> None:
+        self._repo_root = repo_root
+        self._excludes = DEFAULT_EXCLUDES if excludes is None else excludes
+        self._allow_names = frozenset(allow_names) if allow_names else None
+
+    async def grep(
+        self,
+        *,
+        pattern: str,
+        path: str,
+        glob: str | None = None,
+        context_lines: int | None = None,
+        case_sensitive: bool | None = None,
+    ) -> GrepResult:
+        try:
+            abs_path = resolve_under_repo(self._repo_root, path)
+        except ValueError as err:
+            return GrepResult(error=f"[PATH ERROR] {err}")
+
+        if not os.path.exists(abs_path):
+            return GrepResult()
+
+        if abs_path == os.path.abspath(self._repo_root):
+            target_arg = "."
+        else:
+            target_arg = to_repo_relative(self._repo_root, abs_path)
+
+        context = str(context_lines) if context_lines is not None else "1"
+        args = [
+            "--no-config",
+            "--no-heading",
+            "--with-filename",
+            "--line-number",
+            "--color=never",
+            "--trim",
+            "--max-columns=400",
+            "-C",
+            context,
+        ]
+        if case_sensitive is False:
+            args.append("--ignore-case")
+        if glob:
+            args += ["--glob", glob]
+        for exclude in self._excludes:
+            if self._allow_names is not None and exclude in self._allow_names:
+                continue
+            args += ["-g", f"!{exclude}"]
+        args.append(pattern)
+        args.append(target_arg or ".")
+
+        res = await asyncio.to_thread(_run_ripgrep, args, self._repo_root)
+
+        if res.exit_code == -1:
+            detail = "\nExit code: -1" + (f"\nDetails: {res.stderr}" if res.stderr else "")
+            return GrepResult(error=_RIPGREP_NOT_AVAILABLE + detail)
+        # rg exits 1 when there are simply no matches -- that is not an error.
+        if res.exit_code not in (0, 1):
+            suffix = f": {res.stderr}" if res.stderr else ""
+            return GrepResult(
+                error=f"[RIPGREP ERROR] grep failed with exit code {res.exit_code}{suffix}"
+            )
+
+        lines = [line for line in res.stdout.strip().splitlines() if line]
+        return GrepResult(lines=_truncate(lines, WARP_GREP_MAX_OUTPUT_LINES, "lines"))
+
+    async def read(
+        self,
+        *,
+        path: str,
+        start_line: int | None = None,
+        end_line: int | None = None,
+    ) -> ReadResult:
+        try:
+            abs_path = resolve_under_repo(self._repo_root, path)
+        except ValueError as err:
+            return ReadResult(error=f"[PATH ERROR] {err}")
+
+        if not os.path.isfile(abs_path):
+            return ReadResult(
+                error=(
+                    f'[FILE NOT FOUND] You tried to read "{path}" but there is no file at this '
+                    "path. Double-check the path exists and is spelled correctly."
+                )
+            )
+        if os.path.islink(abs_path):
+            return ReadResult(
+                error=(
+                    f'[SYMLINK] You tried to read "{path}" but this is a symlink. '
+                    "Try reading the actual file it points to instead."
+                )
+            )
+        if not is_textual_file(abs_path):
+            return ReadResult(
+                error=(
+                    f'[UNREADABLE FILE] You tried to read "{path}" but this file is either too '
+                    "large or not a text file, so it cannot be read. Try a different file."
+                )
+            )
+
+        try:
+            content = await asyncio.to_thread(_read_text, abs_path)
+        except OSError as err:
+            return ReadResult(error=f'[READ ERROR] Failed to read "{path}": {err}')
+
+        # Preserve newline-driven line count, matching JS split(/\r?\n/).
+        file_lines = content.split("\n")
+        total = len(file_lines)
+
+        start_valid = start_line is None or (math.isfinite(start_line) and start_line > 0)
+        end_valid = end_line is None or (math.isfinite(end_line) and end_line > 0)
+
+        start = 1
+        end = total
+        if start_valid and end_valid:
+            start = start_line if start_line is not None else 1
+            end = min(end_line if end_line is not None else total, total)
+            if (start > total and total > 0) or start > end:
+                start, end = 1, total
+
+        out = [f"{i}|{file_lines[i - 1] if i - 1 < total else ''}" for i in range(start, end + 1)]
+        return ReadResult(lines=_truncate(out, WARP_GREP_MAX_READ_LINES, "lines"))
+
+    async def list_directory(
+        self,
+        *,
+        path: str,
+        pattern: str | None = None,
+        max_results: int | None = None,
+        max_depth: int | None = None,
+    ) -> list[ListDirectoryEntry]:
+        try:
+            abs_path = resolve_under_repo(self._repo_root, path)
+        except ValueError:
+            return []
+        if not os.path.isdir(abs_path):
+            return []
+
+        limit = max_results if max_results is not None else WARP_GREP_MAX_OUTPUT_LINES
+        depth_cap = max_depth if max_depth is not None else WARP_GREP_MAX_LIST_DEPTH
+        regex = re.compile(pattern) if pattern else None
+
+        results: list[ListDirectoryEntry] = []
+        deadline = time.monotonic() + _LIST_TIMEOUT_MS / 1000
+
+        def walk(directory: str, depth: int) -> None:
+            if time.monotonic() > deadline:
+                return
+            if depth > depth_cap or len(results) >= limit:
+                return
+            try:
+                entries = sorted(os.scandir(directory), key=lambda e: e.name)
+            except OSError:
+                return
+            for entry in entries:
+                if time.monotonic() > deadline or len(results) >= limit:
+                    break
+                if should_skip(entry.name, self._allow_names):
+                    continue
+                if regex is not None and not regex.search(entry.name):
+                    continue
+                is_dir = entry.is_dir(follow_symlinks=False)
+                results.append(
+                    ListDirectoryEntry(
+                        name=entry.name,
+                        path=to_repo_relative(self._repo_root, entry.path),
+                        type="dir" if is_dir else "file",
+                        depth=depth,
+                    )
+                )
+                if is_dir:
+                    walk(entry.path, depth + 1)
+
+        await asyncio.to_thread(walk, abs_path, 0)
+        return results
+
+
+def _read_text(file_path: str) -> str:
+    with open(file_path, encoding="utf-8", errors="replace") as fh:
+        return fh.read()

morphsdk/_providers/remote.py

@@ -0,0 +1,161 @@
+"""Remote-command-backed WarpGrep provider.
+
+Wraps three user-supplied async callables (``grep`` / ``read`` / ``list_dir``)
+that each return raw stdout, and handles all parsing/formatting internally --
+mirroring the TypeScript ``RemoteCommandsProvider``.  Pair it with
+:func:`~morphsdk._providers.code_storage_http.create_code_storage_http_commands`
+to search GitHub repos indexed by the Morph code-storage service, or supply your
+own sandbox commands.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Awaitable
+from typing import Callable
+
+from morphsdk._constants import (
+    WARP_GREP_MAX_LIST_DEPTH,
+    WARP_GREP_MAX_OUTPUT_LINES,
+    WARP_GREP_MAX_READ_LINES,
+)
+
+from ._filter import should_skip
+from .base import GrepResult, ListDirectoryEntry, ReadResult, WarpGrepProvider
+
+# Sentinel matching the TS read default (`end ?? 1_000_000`).
+_READ_END_DEFAULT = 1_000_000
+
+#: ``grep(pattern, path, glob)`` -> raw stdout.
+GrepCommand = Callable[[str, str, "str | None"], Awaitable[str]]
+#: ``read(path, start, end)`` -> raw file content.
+ReadCommand = Callable[[str, int, int], Awaitable[str]]
+#: ``list_dir(path, max_depth)`` -> raw newline-delimited paths.
+ListDirCommand = Callable[[str, int], Awaitable[str]]
+
+
+class RemoteCommands:
+    """Bundle of the three remote command callables consumed by the provider."""
+
+    def __init__(
+        self,
+        *,
+        grep: GrepCommand,
+        read: ReadCommand,
+        list_dir: ListDirCommand,
+    ) -> None:
+        self.grep = grep
+        self.read = read
+        self.list_dir = list_dir
+
+
+def _truncate(lines: list[str], limit: int, unit: str) -> list[str]:
+    if len(lines) <= limit:
+        return lines
+    truncated = lines[:limit]
+    truncated.append(f"... (output truncated at {limit} of {len(lines)} {unit})")
+    return truncated
+
+
+class RemoteCommandsProvider(WarpGrepProvider):
+    """Adapts a :class:`RemoteCommands` bundle into a full provider."""
+
+    def __init__(self, repo_root: str, commands: RemoteCommands) -> None:
+        self._repo_root = repo_root
+        self._commands = commands
+
+    async def grep(
+        self,
+        *,
+        pattern: str,
+        path: str,
+        glob: str | None = None,
+        context_lines: int | None = None,
+        case_sensitive: bool | None = None,
+    ) -> GrepResult:
+        try:
+            stdout = await self._commands.grep(pattern, path, glob)
+        except Exception as err:  # noqa: BLE001 - surface as graceful agent error
+            return GrepResult(error=f"[GREP ERROR] {err}")
+        lines = [line for line in (stdout or "").strip().splitlines() if line]
+        return GrepResult(lines=_truncate(lines, WARP_GREP_MAX_OUTPUT_LINES, "lines"))
+
+    async def read(
+        self,
+        *,
+        path: str,
+        start_line: int | None = None,
+        end_line: int | None = None,
+    ) -> ReadResult:
+        start_valid = start_line is None or start_line > 0
+        end_valid = end_line is None or end_line > 0
+        range_valid = (
+            start_valid
+            and end_valid
+            and (start_line is None or end_line is None or start_line <= end_line)
+        )
+
+        start = start_line if (range_valid and start_line is not None) else 1
+        end = end_line if (range_valid and end_line is not None) else _READ_END_DEFAULT
+
+        try:
+            stdout = await self._commands.read(path, start, end)
+        except Exception as err:  # noqa: BLE001
+            return ReadResult(error=f"[READ ERROR] {err}")
+
+        content_lines = (stdout or "").split("\n")
+        # Drop the trailing empty element left by a trailing newline (e.g. sed output).
+        if content_lines and content_lines[-1] == "":
+            content_lines.pop()
+
+        lines = [f"{start + idx}|{content}" for idx, content in enumerate(content_lines)]
+        return ReadResult(lines=_truncate(lines, WARP_GREP_MAX_READ_LINES, "lines"))
+
+    async def list_directory(
+        self,
+        *,
+        path: str,
+        pattern: str | None = None,
+        max_results: int | None = None,
+        max_depth: int | None = None,
+    ) -> list[ListDirectoryEntry]:
+        depth = max_depth if max_depth is not None else WARP_GREP_MAX_LIST_DEPTH
+        limit = max_results if max_results is not None else WARP_GREP_MAX_OUTPUT_LINES
+
+        try:
+            stdout = await self._commands.list_dir(path, depth)
+        except Exception:  # noqa: BLE001 - mirror LocalRipgrepProvider's empty-on-error
+            return []
+
+        paths = [p for p in (stdout or "").strip().splitlines() if p]
+        regex = re.compile(pattern) if pattern else None
+        entries: list[ListDirectoryEntry] = []
+
+        for full_path in paths:
+            if full_path == path or full_path == self._repo_root:
+                continue
+            name = full_path.rsplit("/", 1)[-1]
+            if should_skip(name):
+                continue
+            if regex is not None and not regex.search(name):
+                continue
+
+            relative = full_path
+            if full_path.startswith(self._repo_root):
+                relative = full_path[len(self._repo_root) :].lstrip("/")
+
+            entry_depth = max(0, len([p for p in relative.split("/") if p]) - 1)
+            # Sandbox `find` rarely reports type; infer from a trailing extension.
+            has_extension = "." in name and not name.startswith(".")
+            entries.append(
+                ListDirectoryEntry(
+                    name=name,
+                    path=relative,
+                    type="file" if has_extension else "dir",
+                    depth=entry_depth,
+                )
+            )
+            if len(entries) >= limit:
+                break
+
+        return entries

morphsdk/_version.py

@@ -0,0 +1 @@
+__version__ = "0.2.5"

morphsdk/adapters/__init__.py

@@ -0,0 +1 @@
+"""Framework adapters for generating tool definitions compatible with LLM SDKs."""