maina 0.1.0__tar.gz

maina-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vishal Mishra
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

maina-0.1.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: maina
+Version: 0.1.0
+Summary: Use non-Python CLIs from Python with native-like APIs
+Keywords: cli,subprocess,tools,registry,wrapper,mise
+Author: Vishal Mishra
+Author-email: Vishal Mishra <vishal.k.mishra2@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: requests>=2.32
+Requires-Dist: typer>=0.12
+Requires-Python: >=3.11.4
+Project-URL: Homepage, https://inquilabee.github.io/maina/
+Project-URL: Documentation, https://inquilabee.github.io/maina/
+Project-URL: Repository, https://github.com/inquilabee/maina
+Project-URL: Changelog, https://github.com/inquilabee/maina/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/inquilabee/maina/issues
+Description-Content-Type: text/markdown
+
+# ![maina](https://raw.githubusercontent.com/inquilabee/maina/main/docs/images/maina-mark.svg) maina
+
+[![CI](https://github.com/inquilabee/maina/actions/workflows/ci.yml/badge.svg)](https://github.com/inquilabee/maina/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/inquilabee/maina/blob/main/LICENSE)
+[![Python 3.11.4+](https://img.shields.io/badge/python-3.11.4%2B-blue.svg)](https://github.com/inquilabee/maina/blob/main/pyproject.toml)
+
+Call non-Python CLIs from Python. Describe a tool once in a YAML manifest;
+`Tool(name)` installs or finds the executable, maps keyword arguments to argv,
+runs the process, and returns a structured result — no hand-written install,
+argv, or environment plumbing.
+
+maina ships **the engine and the manifest contract, not a tool catalog**: you
+register your own manifests (or your app does).
+
+## Install
+
+```bash
+pip install maina      # or: uv add maina
+```
+
+Python 3.11.4 or newer, on Linux or macOS.
+
+## A first tool
+
+`my_tools/greet.yaml` — wrap the `echo` already on your `PATH`:
+
+```yaml
+cli: echo
+install: {backend: path}
+args:
+  message: {positional: true, required: true}
+```
+
+```python
+from pathlib import Path
+
+import maina
+
+app = maina.register(maina.Runtime.preferred(), registry_dirs=[Path("my_tools")])
+result = app.tool("greet")(message="hello from maina")
+print(result.ok, result.exit_code, repr(result.raw))
+# True 0 'hello from maina\n'
+```
+
+Swap `backend: path` for `github`, `npm`, `pip`, or `script` and maina downloads
+and caches the tool for you (digest-pinned if you give it a `sha256`). The
+[quickstart](https://inquilabee.github.io/maina/user/quickstart/) walks through a
+real `shellcheck` manifest with a JSON parser.
+
+## What you get
+
+- **Five install backends** — an executable already on `PATH`, GitHub release
+  assets, npm packages, pip packages (one venv per tool), and repo-local scripts —
+  with `mise`-provisioned language runtimes when a manifest pins one.
+- **Manifest to argv** — flags, positionals, repeats, defaults, subcommand
+  families, and `extends` inheritance. Commands are argv lists, never a shell string.
+- **Structured results** — raw stdout, a parsed value (`json` and friends, or your
+  own parser), exit code, stderr, timing. `raise_for_status()` when you want exceptions.
+- **Safe-by-default runs** — per-call `timeout`, bounded output, `env_allow` to keep
+  secrets out of third-party binaries, verified archive extraction.
+- **A CLI** — `maina list | describe | validate | prepare | run`.
+- **Typed** — ships `py.typed`; errors derive from `MainaError`.
+
+## Platform support and stability
+
+Linux and macOS are supported. Windows is not: the install lock is a no-op there and
+archive extraction assumes Unix semantics.
+
+maina is **Beta (0.x)**. `Tool`, the manifest schema, `ToolResult`, and the exception
+types are the stable core. `MainaApp`, `register`, the process-session helpers
+(`runtime`, `use`, `isolated`), and the backend/runtime protocols may change before 1.0.
+
+## Documentation
+
+The [user guide](https://inquilabee.github.io/maina/) covers the
+[quickstart](https://inquilabee.github.io/maina/user/quickstart/),
+[manifest schema](https://inquilabee.github.io/maina/user/manifests/),
+[install backends](https://inquilabee.github.io/maina/user/backends/),
+[parsers](https://inquilabee.github.io/maina/user/parsers/),
+[extending maina](https://inquilabee.github.io/maina/user/extending/) and the
+[CLI](https://inquilabee.github.io/maina/user/cli/).
+Worked catalogs live in [`examples/`](https://github.com/inquilabee/maina/tree/main/examples),
+including 30 real CLIs in [`examples/wild_catalog`](https://github.com/inquilabee/maina/tree/main/examples/wild_catalog).
+
+## Security
+
+A registered registry directory is trusted code — it can ship a `parsers/*.py` that
+maina imports and runs in-process, and `Runtime.preferred()` honours `$MAINA_REGISTRY`
+unless you pass `use_env=False`. Read the
+[security model](https://inquilabee.github.io/maina/user/security/) before pointing
+maina at a catalog you did not write, and report vulnerabilities as described in the
+[security policy](https://github.com/inquilabee/maina/blob/main/SECURITY.md).
+
+## Contributing
+
+See [contributing guide](https://github.com/inquilabee/maina/blob/main/CONTRIBUTING.md).
+MIT licensed.

maina-0.1.0/README.md

@@ -0,0 +1,97 @@
+# ![maina](https://raw.githubusercontent.com/inquilabee/maina/main/docs/images/maina-mark.svg) maina
+
+[![CI](https://github.com/inquilabee/maina/actions/workflows/ci.yml/badge.svg)](https://github.com/inquilabee/maina/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/inquilabee/maina/blob/main/LICENSE)
+[![Python 3.11.4+](https://img.shields.io/badge/python-3.11.4%2B-blue.svg)](https://github.com/inquilabee/maina/blob/main/pyproject.toml)
+
+Call non-Python CLIs from Python. Describe a tool once in a YAML manifest;
+`Tool(name)` installs or finds the executable, maps keyword arguments to argv,
+runs the process, and returns a structured result — no hand-written install,
+argv, or environment plumbing.
+
+maina ships **the engine and the manifest contract, not a tool catalog**: you
+register your own manifests (or your app does).
+
+## Install
+
+```bash
+pip install maina      # or: uv add maina
+```
+
+Python 3.11.4 or newer, on Linux or macOS.
+
+## A first tool
+
+`my_tools/greet.yaml` — wrap the `echo` already on your `PATH`:
+
+```yaml
+cli: echo
+install: {backend: path}
+args:
+  message: {positional: true, required: true}
+```
+
+```python
+from pathlib import Path
+
+import maina
+
+app = maina.register(maina.Runtime.preferred(), registry_dirs=[Path("my_tools")])
+result = app.tool("greet")(message="hello from maina")
+print(result.ok, result.exit_code, repr(result.raw))
+# True 0 'hello from maina\n'
+```
+
+Swap `backend: path` for `github`, `npm`, `pip`, or `script` and maina downloads
+and caches the tool for you (digest-pinned if you give it a `sha256`). The
+[quickstart](https://inquilabee.github.io/maina/user/quickstart/) walks through a
+real `shellcheck` manifest with a JSON parser.
+
+## What you get
+
+- **Five install backends** — an executable already on `PATH`, GitHub release
+  assets, npm packages, pip packages (one venv per tool), and repo-local scripts —
+  with `mise`-provisioned language runtimes when a manifest pins one.
+- **Manifest to argv** — flags, positionals, repeats, defaults, subcommand
+  families, and `extends` inheritance. Commands are argv lists, never a shell string.
+- **Structured results** — raw stdout, a parsed value (`json` and friends, or your
+  own parser), exit code, stderr, timing. `raise_for_status()` when you want exceptions.
+- **Safe-by-default runs** — per-call `timeout`, bounded output, `env_allow` to keep
+  secrets out of third-party binaries, verified archive extraction.
+- **A CLI** — `maina list | describe | validate | prepare | run`.
+- **Typed** — ships `py.typed`; errors derive from `MainaError`.
+
+## Platform support and stability
+
+Linux and macOS are supported. Windows is not: the install lock is a no-op there and
+archive extraction assumes Unix semantics.
+
+maina is **Beta (0.x)**. `Tool`, the manifest schema, `ToolResult`, and the exception
+types are the stable core. `MainaApp`, `register`, the process-session helpers
+(`runtime`, `use`, `isolated`), and the backend/runtime protocols may change before 1.0.
+
+## Documentation
+
+The [user guide](https://inquilabee.github.io/maina/) covers the
+[quickstart](https://inquilabee.github.io/maina/user/quickstart/),
+[manifest schema](https://inquilabee.github.io/maina/user/manifests/),
+[install backends](https://inquilabee.github.io/maina/user/backends/),
+[parsers](https://inquilabee.github.io/maina/user/parsers/),
+[extending maina](https://inquilabee.github.io/maina/user/extending/) and the
+[CLI](https://inquilabee.github.io/maina/user/cli/).
+Worked catalogs live in [`examples/`](https://github.com/inquilabee/maina/tree/main/examples),
+including 30 real CLIs in [`examples/wild_catalog`](https://github.com/inquilabee/maina/tree/main/examples/wild_catalog).
+
+## Security
+
+A registered registry directory is trusted code — it can ship a `parsers/*.py` that
+maina imports and runs in-process, and `Runtime.preferred()` honours `$MAINA_REGISTRY`
+unless you pass `use_env=False`. Read the
+[security model](https://inquilabee.github.io/maina/user/security/) before pointing
+maina at a catalog you did not write, and report vulnerabilities as described in the
+[security policy](https://github.com/inquilabee/maina/blob/main/SECURITY.md).
+
+## Contributing
+
+See [contributing guide](https://github.com/inquilabee/maina/blob/main/CONTRIBUTING.md).
+MIT licensed.

maina-0.1.0/pyproject.toml

@@ -0,0 +1,93 @@
+[project]
+name = "maina"
+version = "0.1.0"
+description = "Use non-Python CLIs from Python with native-like APIs"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "cli",
+    "subprocess",
+    "tools",
+    "registry",
+    "wrapper",
+    "mise",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Build Tools",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+requires-python = ">=3.11.4"
+dependencies = [
+    "pyyaml>=6.0",
+    "requests>=2.32",
+    "typer>=0.12",
+]
+
+[[project.authors]]
+name = "Vishal Mishra"
+email = "vishal.k.mishra2@gmail.com"
+
+[project.urls]
+Homepage = "https://inquilabee.github.io/maina/"
+Documentation = "https://inquilabee.github.io/maina/"
+Repository = "https://github.com/inquilabee/maina"
+Changelog = "https://github.com/inquilabee/maina/blob/main/CHANGELOG.md"
+Issues = "https://github.com/inquilabee/maina/issues"
+
+[project.scripts]
+maina = "maina.cli:main"
+
+[dependency-groups]
+dev = [
+    "mkdocs-material>=9.5",
+    "pre-commit>=4.0",
+    "pytest>=8.0",
+    "ruff>=0.9",
+    "shipgate>=0.1.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.19,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "maina"
+module-root = "src"
+
+[tool.deptry]
+known_first_party = ["maina"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = [
+    "src",
+    "tests",
+]
+
+[tool.ruff.format]
+exclude = ["*.md"]
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "B",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-m 'not integration'"
+markers = ["integration: hits network, mise, npm, or other external services"]

maina-0.1.0/pyproject.toml.orig

@@ -0,0 +1,85 @@
+[project]
+name = "maina"
+version = "0.1.0"
+description = "Use non-Python CLIs from Python with native-like APIs"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Vishal Mishra", email = "vishal.k.mishra2@gmail.com" }
+]
+keywords = ["cli", "subprocess", "tools", "registry", "wrapper", "mise"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Build Tools",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+requires-python = ">=3.11.4"
+dependencies = [
+    "pyyaml>=6.0",
+    "requests>=2.32",
+    "typer>=0.12",
+]
+
+[project.urls]
+Homepage = "https://inquilabee.github.io/maina/"
+Documentation = "https://inquilabee.github.io/maina/"
+Repository = "https://github.com/inquilabee/maina"
+Changelog = "https://github.com/inquilabee/maina/blob/main/CHANGELOG.md"
+Issues = "https://github.com/inquilabee/maina/issues"
+
+[project.scripts]
+maina = "maina.cli:main"
+
+[dependency-groups]
+dev = [
+    "mkdocs-material>=9.5",
+    "pre-commit>=4.0",
+    "pytest>=8.0",
+    "ruff>=0.9",
+    "shipgate>=0.1.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.19,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "maina"
+module-root = "src"
+
+[tool.deptry]
+# First-party packages (not reported as missing third-party deps).
+known_first_party = ["maina"]
+
+# [tool.deptry.per_rule_ignores]
+# DEP002 = ["optional-extra-package"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = ["src", "tests"]
+
+[tool.ruff.format]
+# Docs code blocks keep their hand-aligned comments.
+exclude = ["*.md"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+# Hermetic by default; run the network/mise/npm suite with: pytest -m integration
+addopts = "-m 'not integration'"
+markers = [
+    "integration: hits network, mise, npm, or other external services",
+]

maina-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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)