maina 0.1.0__py3-none-any.whl

maina/__init__.py

@@ -0,0 +1,76 @@
+"""Call non-Python CLIs from Python via a registry-first Tool runtime."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError as _PackageNotFoundError
+from importlib.metadata import version as _version
+
+from maina.core.errors import (
+    AbstractToolError,
+    ArgError,
+    InstallError,
+    MainaError,
+    ManifestError,
+    ParseError,
+    RegisterError,
+    RuntimeProvisionError,
+    ToolExecError,
+    ToolExitError,
+    ToolOutputError,
+    ToolTimeoutError,
+    UnsupportedPlatformError,
+)
+from maina.core.parsers import FunctionParser, parser
+from maina.core.protocols import (
+    InstallContext,
+    InstallerBackend,
+    LanguageRuntimeProvider,
+    Parser,
+)
+from maina.core.registry import ArgSpec, InstallSpec, Manifest, OutputSpec, Registry
+from maina.core.result import ToolResult
+from maina.runner import ToolRunner
+from maina.runtime import Runtime, isolated, runtime, use
+from maina.tool import MainaApp, Tool, register
+
+try:
+    __version__ = _version("maina")
+except _PackageNotFoundError:  # pragma: no cover - source checkout without install
+    __version__ = "0.0.0+unknown"
+
+__all__ = [
+    "AbstractToolError",
+    "ArgError",
+    "ArgSpec",
+    "FunctionParser",
+    "InstallContext",
+    "InstallError",
+    "InstallSpec",
+    "InstallerBackend",
+    "LanguageRuntimeProvider",
+    "MainaApp",
+    "MainaError",
+    "Manifest",
+    "ManifestError",
+    "OutputSpec",
+    "ParseError",
+    "Parser",
+    "RegisterError",
+    "Registry",
+    "Runtime",
+    "RuntimeProvisionError",
+    "Tool",
+    "ToolExecError",
+    "ToolExitError",
+    "ToolOutputError",
+    "ToolResult",
+    "ToolRunner",
+    "ToolTimeoutError",
+    "UnsupportedPlatformError",
+    "__version__",
+    "isolated",
+    "parser",
+    "register",
+    "runtime",
+    "use",
+]

maina/backends/__init__.py

@@ -0,0 +1,11 @@
+"""Shipped installer backends."""
+
+from __future__ import annotations
+
+from maina.backends.github import GithubBackend
+from maina.backends.npm import NpmBackend
+from maina.backends.path import PathBackend
+from maina.backends.pip import PipBackend
+from maina.backends.script import ScriptBackend
+
+__all__ = ["GithubBackend", "NpmBackend", "PathBackend", "PipBackend", "ScriptBackend"]

maina/backends/archive.py

@@ -0,0 +1,163 @@
+"""Shared archive download/extract helpers for installer backends."""
+
+from __future__ import annotations
+
+import hashlib
+import tempfile
+import time
+from contextlib import suppress
+from pathlib import Path
+from typing import TYPE_CHECKING
+from urllib.parse import urljoin, urlparse
+
+import requests
+
+from maina.backends.unpack import UNPACK_ERRORS, ArchiveUnpacker
+from maina.core.errors import InstallError
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+# Soft cap for streamed release assets (GitHub binaries, etc.).
+DEFAULT_MAX_BYTES = 512 * 1024 * 1024
+CHUNK_SIZE = 64 * 1024
+# Wall-clock cap on one download; the per-read timeout alone lets a slow-drip server hold it open.
+DOWNLOAD_MAX_SECONDS = 30 * 60
+REDIRECT_STATUSES = frozenset({301, 302, 303, 307, 308})
+MAX_REDIRECT_HOPS = 5
+
+
+class ArchiveFetcher(ArchiveUnpacker):
+    """Download https assets and extract binaries into a destination directory.
+
+    When ``allowed_redirect_hosts`` is given, redirects are resolved hop by hop
+    and every hop host must match one of those names (exact or ``.suffix``);
+    this keeps a github download from being bounced to an arbitrary host. With
+    ``None`` (default) redirects are followed normally.
+    """
+
+    def __init__(
+        self,
+        *,
+        session: requests.Session | None = None,
+        max_bytes: int = DEFAULT_MAX_BYTES,
+        allowed_redirect_hosts: Iterable[str] | None = None,
+    ) -> None:
+        self._session = session or requests.Session()
+        self.max_bytes = max_bytes
+        self._allowed_hosts = (
+            None if allowed_redirect_hosts is None else frozenset(allowed_redirect_hosts)
+        )
+
+    def close(self) -> None:
+        """Close the underlying :class:`requests.Session`."""
+        self._session.close()
+
+    def download_and_extract(
+        self,
+        url: str,
+        dest_dir: Path,
+        *,
+        binary: str,
+        asset_name: str,
+        sha256: str | None = None,
+        allow_any_executable: bool = False,
+    ) -> None:
+        """Download an asset and extract/copy the binary into dest_dir.
+
+        When *sha256* is given, the downloaded asset must match that hex digest
+        before it is extracted; a mismatch raises :class:`InstallError`.
+        """
+        try:
+            dest_dir.mkdir(parents=True, exist_ok=True)
+            with tempfile.TemporaryDirectory() as tmp:
+                tmp_path = Path(tmp)
+                # asset_name is validated at manifest load, but never let it escape.
+                archive = tmp_path / Path(asset_name).name
+                self.fetch_https(url, archive)
+                if sha256:
+                    self._verify_sha256(archive, expected=sha256, url=url)
+                self.extract_archive(
+                    archive,
+                    tmp_path,
+                    dest_dir,
+                    binary=binary,
+                    asset_name=asset_name,
+                    allow_any_executable=allow_any_executable,
+                )
+        except UNPACK_ERRORS as exc:
+            raise InstallError(f"could not install {asset_name} from {url}: {exc}") from exc
+
+    @staticmethod
+    def _verify_sha256(archive: Path, *, expected: str, url: str) -> None:
+        """Raise unless *archive* hashes to *expected* (case-insensitive hex)."""
+        with archive.open("rb") as handle:
+            actual = hashlib.file_digest(handle, "sha256").hexdigest()
+        if actual.lower() != expected.strip().lower():
+            raise InstallError(
+                f"sha256 mismatch for {url}: expected {expected.strip().lower()}, got {actual}"
+            )
+
+    def fetch_https(self, url: str, dest: Path) -> None:
+        """Stream a URL that must use the https scheme, enforcing a size cap."""
+        if urlparse(url).scheme != "https" or not urlparse(url).netloc:
+            raise InstallError(f"refusing non-https download URL: {url}")
+        if self._allowed_hosts is None:
+            self._stream_get(url, dest, allow_redirects=True)
+            return
+        current = url
+        for _ in range(MAX_REDIRECT_HOPS):
+            self._require_allowed_host(current)
+            location = self._stream_get(current, dest, allow_redirects=False)
+            if location is None:
+                return
+            current = urljoin(current, location)
+        raise InstallError(f"too many redirects fetching {url}")
+
+    def _stream_get(self, url: str, dest: Path, *, allow_redirects: bool) -> str | None:
+        """GET *url*; write the body, or return a redirect Location to follow."""
+        try:
+            with self._session.get(
+                url, timeout=120, stream=True, allow_redirects=allow_redirects
+            ) as response:
+                if not allow_redirects and response.status_code in REDIRECT_STATUSES:
+                    location = response.headers.get("Location")
+                    if not location:
+                        raise InstallError(f"redirect missing Location: {url}")
+                    return location
+                response.raise_for_status()
+                self._write_capped_stream(response, dest, url=url)
+        except requests.RequestException as exc:
+            raise InstallError(f"download failed for {url}: {exc}") from exc
+        return None
+
+    def _require_allowed_host(self, url: str) -> None:
+        parsed = urlparse(url)
+        host = (parsed.hostname or "").lower()
+        listed = self._host_in_allowlist(host)
+        if parsed.scheme != "https" or parsed.username is not None or not host or not listed:
+            raise InstallError(f"refusing redirect off allowed hosts: {url}")
+
+    def _host_in_allowlist(self, host: str) -> bool:
+        allowed = self._allowed_hosts or frozenset()
+        return any(host == name or host.endswith(f".{name}") for name in allowed)
+
+    def _write_capped_stream(self, response: requests.Response, dest: Path, *, url: str) -> None:
+        """Write response body to dest, rejecting Content-Length or body over max_bytes."""
+        content_length = response.headers.get("Content-Length")
+        if content_length is not None:
+            with suppress(ValueError):
+                if int(content_length) > self.max_bytes:
+                    raise InstallError(f"download exceeds size cap ({self.max_bytes} bytes): {url}")
+        total = 0
+        deadline = time.monotonic() + DOWNLOAD_MAX_SECONDS
+        with dest.open("wb") as out:
+            for chunk in response.iter_content(chunk_size=CHUNK_SIZE):
+                if not chunk:
+                    continue
+                if time.monotonic() > deadline:
+                    raise InstallError(f"download took over {DOWNLOAD_MAX_SECONDS}s: {url}")
+                total += len(chunk)
+                if total > self.max_bytes:
+                    raise InstallError(f"download exceeds size cap ({self.max_bytes} bytes): {url}")
+                out.write(chunk)

maina/backends/github.py

@@ -0,0 +1,113 @@
+"""GitHub release asset installer backend."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+from urllib.parse import quote
+
+from maina.backends.archive import ArchiveFetcher
+from maina.core.errors import InstallError
+from maina.core.platform import platform_key
+from maina.core.protocols import InstallerBackend
+from maina.core.registry.common import is_unsafe_segment
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from maina.core.protocols import InstallContext
+    from maina.core.registry import Manifest
+
+
+GITHUB_DOWNLOAD_HOSTS = frozenset(
+    {"github.com", "api.github.com", "githubusercontent.com", "codeload.github.com"}
+)
+
+
+class GithubBackend(InstallerBackend):
+    """Download a GitHub release asset into the tool cache (``backend: github``)."""
+
+    def __init__(self, fetcher: ArchiveFetcher | None = None) -> None:
+        self._fetcher = fetcher or ArchiveFetcher(allowed_redirect_hosts=GITHUB_DOWNLOAD_HOSTS)
+
+    @property
+    def name(self) -> str:
+        return "github"
+
+    def close(self) -> None:
+        """Close the shared HTTP session."""
+        self._fetcher.close()
+
+    def resolve(
+        self,
+        manifest: Manifest,
+        *,
+        version: str,
+        env: dict[str, str],
+        ctx: InstallContext,
+    ) -> tuple[str, dict[str, str]]:
+        exe = self._resolve_github(manifest, version, ctx)
+        return str(exe), ctx.prepend_path(env, exe.parent)
+
+    @staticmethod
+    def probe(manifest: Manifest, *, version: str, ctx: InstallContext) -> bool:
+        """True when the cached release binary already exists (no download)."""
+        binary = manifest.install.binary or manifest.cli
+        cached = ctx.cache_root / "tools" / manifest.cli / version / "bin" / binary
+        return cached.is_file()
+
+    def _resolve_github(self, manifest: Manifest, version: str, ctx: InstallContext) -> Path:
+        """Download a GitHub release asset into the tool cache if needed."""
+        repo, binary = self._install_parts(manifest)
+        key = platform_key()
+        asset = manifest.install.asset_for(key, manifest.version)
+        if not asset:
+            raise InstallError(f"{manifest.id}: no github asset for {key}")
+        if is_unsafe_segment(asset):
+            raise InstallError(
+                f"{manifest.id}: asset name {asset!r} for {key} is not a safe path segment "
+                "(check install.asset_template and os_map / arch_map)"
+            )
+
+        dest_dir = ctx.ensure_tool_bin_dir(manifest.cli, version)
+        dest = dest_dir / binary
+        if dest.is_file():
+            return dest
+
+        # ``version`` is the identity-keyed cache segment; the release tag is the
+        # manifest's own version (or an explicit ``install.tag``).
+        tag = manifest.install.tag or manifest.version
+        url = self._release_url(repo, str(asset), tag=str(tag) if tag else None)
+        self._fetcher.download_and_extract(
+            url,
+            dest_dir,
+            binary=binary,
+            asset_name=str(asset),
+            sha256=manifest.install.sha256.get(key),
+            allow_any_executable=manifest.install.allow_any_executable,
+        )
+        if not dest.is_file():
+            raise InstallError(
+                f"{manifest.id}: downloaded asset but {binary} missing in {dest_dir}"
+            )
+        return dest
+
+    @staticmethod
+    def _install_parts(manifest: Manifest) -> tuple[str, str]:
+        """Validate and return repo and binary name."""
+        install = manifest.install
+        repo = install.repo
+        binary = install.binary or manifest.cli
+        if not repo or not install.has_assets():
+            raise InstallError(
+                f"{manifest.id}: github install needs repo and assets (or asset_template)"
+            )
+        return repo, binary
+
+    @staticmethod
+    def _release_url(repo: str, asset: str, *, tag: str | None) -> str:
+        """Build a GitHub release download URL."""
+        asset_quoted = quote(asset, safe="")
+        tag_quoted = quote(tag or "", safe="")
+        latest = f"https://github.com/{repo}/releases/latest/download/{asset_quoted}"
+        pinned = f"https://github.com/{repo}/releases/download/{tag_quoted}/{asset_quoted}"
+        return pinned if tag and tag != "latest" else latest

maina/backends/npm.py

@@ -0,0 +1,186 @@
+"""npm package installer backend."""
+
+from __future__ import annotations
+
+import json
+import shutil
+from typing import TYPE_CHECKING
+
+from maina.core.errors import InstallError
+from maina.core.protocols import InstallerBackend
+from maina.core.subprocess_utils import (
+    INSTALL_OUTPUT_MAX_BYTES,
+    resolve_within,
+    run_or_wrap_capped,
+)
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from maina.core.protocols import InstallContext
+    from maina.core.registry import Manifest
+
+
+class NpmBackend(InstallerBackend):
+    """Install an npm package into the tool cache (``install.backend: npm``)."""
+
+    @property
+    def name(self) -> str:
+        return "npm"
+
+    def resolve(
+        self,
+        manifest: Manifest,
+        *,
+        version: str,
+        env: dict[str, str],
+        ctx: InstallContext,
+    ) -> tuple[str, dict[str, str]]:
+        exe = self._resolve_npm(manifest, version, env, ctx)
+        return str(exe), ctx.prepend_path(env, exe.parent)
+
+    @staticmethod
+    def probe(manifest: Manifest, *, version: str, ctx: InstallContext) -> bool:
+        """True when the npm bin link already exists in the cache (no install)."""
+        link = (
+            ctx.cache_root
+            / "tools"
+            / manifest.cli
+            / version
+            / "npm"
+            / "node_modules"
+            / ".bin"
+            / manifest.cli
+        )
+        return link.exists()
+
+    def _resolve_npm(
+        self,
+        manifest: Manifest,
+        version: str,
+        env: dict[str, str],
+        ctx: InstallContext,
+    ) -> Path:
+        """Install an npm package into the tool cache and return its bin path.
+
+        *version* is the identity-keyed cache-dir segment; the npm dist-tag /
+        version comes from ``manifest.version``.
+        """
+        package = manifest.install.package or manifest.cli
+        self._ensure_node_on_path(manifest, env, ctx)
+        prefix = ctx.cache_root / "tools" / manifest.cli / version / "npm"
+        link = prefix / "node_modules" / ".bin" / manifest.cli
+        return (
+            link
+            if link.exists()
+            else self._install_package(
+                manifest.cli,
+                package,
+                manifest.version,
+                prefix,
+                link,
+                env,
+                allow_scripts=manifest.install.allow_scripts,
+            )
+        )
+
+    @staticmethod
+    def _ensure_node_on_path(
+        manifest: Manifest,
+        env: dict[str, str],
+        ctx: InstallContext,
+    ) -> None:
+        """Ensure Node is on *env* PATH without clobbering composed bins.
+
+        ``LanguageRuntimeProvider.env`` typically rebuilds PATH from
+        ``os.environ``, which would drop bins prepended by
+        ``Installer._compose_requires_env``. Prefer ``ensure`` +
+        :meth:`InstallContext.prepend_path` on the existing env.
+        """
+        node_version = manifest.requires.get("node") or "latest"
+        if shutil.which("node", path=env.get("PATH")):
+            return
+        # Hand mise the trimmed install env so its subprocesses honour env_allow.
+        bin_dir = ctx.language.ensure("node", node_version, base_env=env)
+        ctx.prepend_path(env, bin_dir)
+
+    @staticmethod
+    def _install_package(
+        cli: str,
+        package: str,
+        version: str | None,
+        prefix: Path,
+        link: Path,
+        env: dict[str, str],
+        *,
+        allow_scripts: bool = False,
+    ) -> Path:
+        """npm install a package into prefix and return its bin link."""
+        prefix.mkdir(parents=True, exist_ok=True)
+        # Anchor the local project so npm does not walk up to a parent
+        # package.json (or a global root) and resolve the bin to an outside
+        # install.
+        anchor = prefix / "package.json"
+        if not anchor.exists():
+            anchor.write_text(
+                json.dumps({"name": f"maina-tool-{cli}", "private": True}) + "\n",
+                encoding="utf-8",
+            )
+        pkg_spec = f"{package}@{version}" if version and version != "default" else package
+        npm = shutil.which("npm", path=env.get("PATH"))
+        if not npm:
+            raise InstallError("npm not found; ensure node runtime via mise")
+        NpmBackend._npm_install(npm, prefix, pkg_spec, env, allow_scripts=allow_scripts)
+        if not (link.is_file() or link.is_symlink()):
+            raise InstallError(f"npm install of {pkg_spec} did not produce {cli}")
+        resolve_within(
+            link,
+            prefix,
+            error_cls=InstallError,
+            message=(
+                f"npm resolved {cli} to {link.resolve()}, outside the tool cache "
+                f"({prefix}); refusing to link an out-of-cache install"
+            ),
+        )
+        return link
+
+    INSTALL_TIMEOUT = 600
+
+    @staticmethod
+    def _npm_install(
+        npm: str,
+        prefix: Path,
+        pkg_spec: str,
+        env: dict[str, str],
+        *,
+        allow_scripts: bool = False,
+    ) -> None:
+        """Run npm install --prefix for a package (local, no lockfile churn).
+
+        ``--ignore-scripts`` by default: a third-party package's install /
+        postinstall lifecycle scripts run with the composed environment, so a
+        manifest must opt in with ``install.allow_scripts: true``.
+        """
+        argv = [
+            npm,
+            "install",
+            "--prefix",
+            str(prefix),
+            "--no-fund",
+            "--no-audit",
+            "--no-package-lock",
+        ]
+        if not allow_scripts:
+            argv.append("--ignore-scripts")
+        argv.extend(["--", pkg_spec])
+        run_or_wrap_capped(
+            argv,
+            env=env,
+            timeout=NpmBackend.INSTALL_TIMEOUT,
+            max_bytes=INSTALL_OUTPUT_MAX_BYTES,
+            error_cls=InstallError,
+            on_timeout=(
+                lambda: f"npm install {pkg_spec} timed out after {NpmBackend.INSTALL_TIMEOUT}s"
+            ),
+            on_failure=lambda detail: f"npm install {pkg_spec} failed: {detail}",
+        )

maina/backends/path.py

@@ -0,0 +1,49 @@
+"""PATH-backed installer backend."""
+
+from __future__ import annotations
+
+import shutil
+from typing import TYPE_CHECKING
+
+from maina.core.errors import InstallError
+from maina.core.protocols import InstallerBackend
+
+if TYPE_CHECKING:
+    from maina.core.protocols import InstallContext
+    from maina.core.registry import Manifest
+
+
+class PathBackend(InstallerBackend):
+    """Resolve a CLI from PATH (``install.backend: path``)."""
+
+    @property
+    def name(self) -> str:
+        return "path"
+
+    def resolve(  # ruff:ignore[no-self-use] - must be an instance method, overrides InstallerBackend.resolve
+        self,
+        manifest: Manifest,
+        *,
+        version: str,
+        env: dict[str, str],
+        ctx: InstallContext,
+    ) -> tuple[str, dict[str, str]]:
+        del version, ctx
+        found = shutil.which(manifest.cli, path=env.get("PATH"))
+        if not found:
+            raise InstallError(
+                f"{manifest.cli!r} not found on PATH — install it, or add an install: block "
+                "(github, npm, pip, script) so maina can fetch it"
+            )
+        return found, env
+
+    @staticmethod
+    def probe(manifest: Manifest, *, version: str, ctx: InstallContext) -> bool:
+        """True when the CLI already resolves on PATH (no side effects).
+
+        Searches ``ctx.probe_path`` — the ambient PATH plus the bin dirs of any
+        already-installed ``requires:`` runtimes — so a tool provided by a pinned
+        runtime is not reported ``missing`` by a check that ``resolve`` passes.
+        """
+        del version
+        return shutil.which(manifest.cli, path=ctx.probe_path) is not None