esp-gsp-tools 0.1.0__tar.gz

esp_gsp_tools-0.1.0/.gitignore

@@ -0,0 +1,3 @@
+.venv/
+__pycache__/
+.pytest_cache/

esp_gsp_tools-0.1.0/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.5
+Name: esp-gsp-tools
+Version: 0.1.0
+Summary: Resolve, verify, cache, and run pinned esp-gsp-tools releases
+Author: Espressif Systems
+License: Apache-2.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: <3.15,>=3.10
+Requires-Dist: cryptography>=44.0.0
+Description-Content-Type: text/markdown
+
+# esp-gsp-tools
+
+`esp-gsp-tools` resolves, verifies, caches, and runs a pinned release of one
+of the supported products:
+
+| Product name | Product |
+| --- | --- |
+| `gspc` | GSPC |
+| `sim` | simulator |
+
+Product names are case-insensitive.
+
+## Run a product
+
+```sh
+python -m gsp.execute --version 0.2.4 gspc pack scene.json -o bundle.gspb
+python -m gsp.execute --no-auto-cache sim --help
+```
+
+All arguments after the product name are passed to that product unchanged.
+`--version` overrides `GSP_VERSION`. A missing cached version is downloaded
+automatically unless `--no-auto-cache` or
+`GSP_TOOLS_NO_AUTO_DOWNLOAD=1` is used.
+
+The direct executable variables are `GSPC_EXECUTABLE` and
+`GSP_SIM_EXECUTABLE`; either takes precedence over the cache and version.
+
+## Manage the cache
+
+The manager requires a product for every version-specific operation. Both
+`VERSION PRODUCT` and `PRODUCT VERSION` are accepted:
+
+```sh
+python -m gsp.manager install 0.2.4 gspc
+python -m gsp.manager fetch sim 0.2.4
+python -m gsp.manager reinstall 0.2.4 GSPC
+python -m gsp.manager path 0.2.4 sim
+python -m gsp.manager remove 0.2.4 gspc
+python -m gsp.manager list sim
+```
+
+The cache defaults to `~/.espressif/esp-gsp-tools` and can be changed with
+`GSP_TOOLS_CACHE_DIR` or `--cache-dir`. `GSP_TOOLS_BASE_URL` overrides the
+single release root URL. The manager appends the product directory (`gspc` or
+`sim`) before the version path. Release archives are authenticated with the
+configured Ed25519 public keys as described by the manifest.
+
+If a product name is not supported, the command explains that the installed
+`esp-gsp-tools` version may be outdated and suggests:
+
+```sh
+python -m pip install -U esp-gsp-tools
+```

esp_gsp_tools-0.1.0/README.md

@@ -0,0 +1,53 @@
+# esp-gsp-tools
+
+`esp-gsp-tools` resolves, verifies, caches, and runs a pinned release of one
+of the supported products:
+
+| Product name | Product |
+| --- | --- |
+| `gspc` | GSPC |
+| `sim` | simulator |
+
+Product names are case-insensitive.
+
+## Run a product
+
+```sh
+python -m gsp.execute --version 0.2.4 gspc pack scene.json -o bundle.gspb
+python -m gsp.execute --no-auto-cache sim --help
+```
+
+All arguments after the product name are passed to that product unchanged.
+`--version` overrides `GSP_VERSION`. A missing cached version is downloaded
+automatically unless `--no-auto-cache` or
+`GSP_TOOLS_NO_AUTO_DOWNLOAD=1` is used.
+
+The direct executable variables are `GSPC_EXECUTABLE` and
+`GSP_SIM_EXECUTABLE`; either takes precedence over the cache and version.
+
+## Manage the cache
+
+The manager requires a product for every version-specific operation. Both
+`VERSION PRODUCT` and `PRODUCT VERSION` are accepted:
+
+```sh
+python -m gsp.manager install 0.2.4 gspc
+python -m gsp.manager fetch sim 0.2.4
+python -m gsp.manager reinstall 0.2.4 GSPC
+python -m gsp.manager path 0.2.4 sim
+python -m gsp.manager remove 0.2.4 gspc
+python -m gsp.manager list sim
+```
+
+The cache defaults to `~/.espressif/esp-gsp-tools` and can be changed with
+`GSP_TOOLS_CACHE_DIR` or `--cache-dir`. `GSP_TOOLS_BASE_URL` overrides the
+single release root URL. The manager appends the product directory (`gspc` or
+`sim`) before the version path. Release archives are authenticated with the
+configured Ed25519 public keys as described by the manifest.
+
+If a product name is not supported, the command explains that the installed
+`esp-gsp-tools` version may be outdated and suggests:
+
+```sh
+python -m pip install -U esp-gsp-tools
+```

esp_gsp_tools-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "esp-gsp-tools"
+version = "0.1.0"
+description = "Resolve, verify, cache, and run pinned esp-gsp-tools releases"
+readme = "README.md"
+requires-python = ">=3.10,<3.15"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Espressif Systems" }]
+dependencies = ["cryptography>=44.0.0"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+]
+
+[project.scripts]
+esp-gsp-tools = "gsp.manager:main"
+
+[dependency-groups]
+dev = ["pytest>=8.3"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/gsp"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

esp_gsp_tools-0.1.0/src/gsp/__init__.py

@@ -0,0 +1,3 @@
+"""Pinned, signed esp-gsp-tools release resolver."""
+
+__version__ = "0.1.0"

esp_gsp_tools-0.1.0/src/gsp/__main__.py

@@ -0,0 +1,9 @@
+import sys
+
+
+if __name__ == "__main__":
+    sys.stderr.write(
+        "Use `python -m gsp.execute PRODUCT` to run a product or "
+        "`python -m gsp.manager` to manage its local cache.\n"
+    )
+    raise SystemExit(2)

esp_gsp_tools-0.1.0/src/gsp/errors.py

@@ -0,0 +1,7 @@
+class GspManagerError(RuntimeError):
+    """A recoverable user-facing manager error."""
+
+
+# Keep the old import available for callers that used the initial package
+# while the public module is migrated from ``gspc`` to ``gsp``.
+GspcManagerError = GspManagerError

esp_gsp_tools-0.1.0/src/gsp/execute.py

@@ -0,0 +1,94 @@
+"""Resolve and execute one product from the esp-gsp-tools distribution."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+from .errors import GspManagerError
+from .manager import GspManager, load_public_keys
+from .products import get_product
+
+
+_TRUE_VALUES = {"1", "true", "yes", "on"}
+
+
+def _automatic_download_disabled() -> bool:
+    value = os.environ.get("GSP_TOOLS_NO_AUTO_DOWNLOAD", "")
+    return value.strip().lower() in _TRUE_VALUES
+
+
+def executable_from_environment(
+    product: str,
+    *,
+    version: str | None = None,
+    no_auto_cache: bool = False,
+) -> Path:
+    selected = get_product(product)
+    direct_path = os.environ.get(selected.executable_environment)
+    if direct_path:
+        executable = Path(direct_path)
+        if not executable.is_file():
+            raise GspManagerError(
+                f"{selected.executable_environment} does not point to a file: {executable}"
+            )
+        return executable
+
+    requested_version = (version or os.environ.get("GSP_VERSION", "")).strip()
+    if not requested_version:
+        raise GspManagerError(
+            "set --version, GSP_VERSION, or the product executable environment variable"
+        )
+    manager = GspManager(product=selected.key, public_keys=load_public_keys(None, []))
+    executable = manager.cached(requested_version)
+    if executable is not None:
+        return executable
+    if no_auto_cache or _automatic_download_disabled():
+        raise GspManagerError(
+            f"{selected.display_name} {requested_version} is not cached and automatic download is disabled; "
+            f"run `python -m gsp.manager install {requested_version} {selected.key}` first"
+        )
+    return manager.resolve(requested_version)
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="python -m gsp.execute",
+        description="Run a selected esp-gsp-tools product.",
+    )
+    parser.add_argument("--version", help="exact product version; defaults to GSP_VERSION")
+    parser.add_argument(
+        "--no-auto-cache",
+        action="store_true",
+        help="do not download a missing version automatically",
+    )
+    parser.add_argument("product", metavar="PRODUCT")
+    parser.add_argument("arguments", nargs=argparse.REMAINDER, metavar="ARGS")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _parser()
+    options = parser.parse_args(sys.argv[1:] if argv is None else argv)
+    executable: Path | None = None
+    try:
+        selected = get_product(options.product)
+        executable = executable_from_environment(
+            selected.key,
+            version=options.version,
+            no_auto_cache=options.no_auto_cache,
+        )
+        return subprocess.run([str(executable), *options.arguments], check=False).returncode
+    except GspManagerError as exc:
+        sys.stderr.write(f"gsp.execute: error: {exc}\n")
+        return 2
+    except OSError as exc:
+        sys.stderr.write(f"gsp.execute: error: cannot run {executable}: {exc}\n")
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

esp_gsp_tools-0.1.0/src/gsp/keys.py

@@ -0,0 +1,16 @@
+"""Trusted GSPC release signing keys.
+
+Populate this mapping when the release signing key is provisioned.  Keeping
+the registry explicit makes key IDs auditable and permits overlapping keys
+during a rotation.
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+BUILTIN_PUBLIC_KEYS: Final[dict[str, str]] = {
+    "gspc-release": "uSVHnMpv03VPGL5FMQm2USELARKeCPRdGsezyqQlQ74=",
+    "gsp-sim-release": "CbVrcYYSPjDt6J7N5v4h80SCcizC8ZW+d6D2Q8Y43iU=",
+    "fa": "S2WEykJ/6KvoIcFGQ9tpa4TkzJrVwwPIddoqko9GNDM="
+}

esp_gsp_tools-0.1.0/src/gsp/manager.py

@@ -0,0 +1,361 @@
+from __future__ import annotations
+
+import argparse
+import base64
+import json
+import os
+import shutil
+import stat
+import subprocess
+import tarfile
+import tempfile
+import time
+import zipfile
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Iterator, Mapping
+from urllib.parse import urlparse
+from urllib.request import Request, urlopen
+
+from .errors import GspManagerError, GspcManagerError
+from .keys import BUILTIN_PUBLIC_KEYS
+from .manifest import Artifact, parse_manifest
+from .platforms import HostPlatform, executable_name
+from .products import Product, get_product
+from .verify import verify_ed25519
+
+DEFAULT_CACHE_DIR = Path.home() / ".espressif" / "esp-gsp-tools"
+DEFAULT_BASE_URL = "https://dl.espressif.com/AE/gsp/"
+
+
+def default_cache_dir() -> Path:
+    return Path(os.environ.get("GSP_TOOLS_CACHE_DIR") or os.environ.get("GSPC_CACHE_DIR", DEFAULT_CACHE_DIR))
+
+
+def default_base_url() -> str:
+    return (os.environ.get("GSP_TOOLS_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+
+
+class GspManager:
+    def __init__(self, product: str = "gspc", *, base_url: str | None = None, cache_dir: Path | None = None, public_keys: Mapping[str, str] | None = None) -> None:
+        self.product = get_product(product)
+        self.base_url = (base_url or default_base_url()).rstrip("/")
+        if urlparse(self.base_url).scheme != "https":
+            raise GspManagerError("release base URL must use HTTPS")
+        self.cache_dir = cache_dir or default_cache_dir()
+        self.public_keys = dict(BUILTIN_PUBLIC_KEYS)
+        if public_keys:
+            self.public_keys.update(public_keys)
+
+    def resolve(self, version: str, *, reinstall: bool = False) -> Path:
+        _validate_version(version)
+        host = HostPlatform.detect()
+        destination = self._destination(version, host)
+        expected_binary = destination / "bin" / executable_name(self.product.binary, host)
+        with _cache_lock(destination.with_name(destination.name + ".lock")):
+            if reinstall and destination.exists():
+                shutil.rmtree(destination)
+            metadata_path = destination / "metadata.json"
+            if expected_binary.is_file() and metadata_path.is_file():
+                self._validate_installed(expected_binary, version)
+                return expected_binary
+            if destination.exists():
+                shutil.rmtree(destination)
+            artifact, manifest_url = self._fetch_artifact(version, host)
+            installed = self._install(destination, artifact, version, host)
+            metadata_path = installed.parent.parent / "metadata.json"
+            metadata_path.write_text(
+                json.dumps({"version": version, "manifest_url": manifest_url, "artifact": artifact.raw}, indent=2) + "\n",
+                encoding="utf-8",
+            )
+            return installed
+
+    def cached(self, version: str) -> Path | None:
+        """Return a verified cached compiler for this host, without networking."""
+        _validate_version(version)
+        host = HostPlatform.detect()
+        destination = self._destination(version, host)
+        binary = destination / "bin" / executable_name(self.product.binary, host)
+        if not binary.is_file() or not (destination / "metadata.json").is_file():
+            return None
+        self._validate_installed(binary, version)
+        return binary
+
+    def remove(self, version: str) -> bool:
+        """Remove exactly one cached version for the current host."""
+        _validate_version(version)
+        host = HostPlatform.detect()
+        destination = self._destination(version, host)
+        with _cache_lock(destination.with_name(destination.name + ".lock")):
+            if not destination.exists():
+                return False
+            shutil.rmtree(destination)
+            try:
+                destination.parent.rmdir()
+            except OSError:
+                pass
+            return True
+
+    def list_cached(self) -> list[tuple[str, str, str, Path]]:
+        """Return (product, version, platform, executable) records installed."""
+        if not self.cache_dir.is_dir():
+            return []
+        records: list[tuple[str, str, str, Path]] = []
+        for metadata in sorted((self.cache_dir / self.product.key).glob("v*/*/metadata.json")):
+            try:
+                version = json.loads(metadata.read_text(encoding="utf-8"))["version"]
+            except (OSError, ValueError, KeyError, TypeError):
+                continue
+            binary_dir = metadata.parent / "bin"
+            binaries = list(binary_dir.glob(f"{self.product.binary}*")) if binary_dir.is_dir() else []
+            if len(binaries) == 1 and isinstance(version, str):
+                records.append((self.product.key, version, metadata.parent.name, binaries[0]))
+        return records
+
+    def _destination(self, version: str, host: HostPlatform) -> Path:
+        return self.cache_dir / self.product.key / f"v{version}" / f"{host.os}-{host.arch}"
+
+    def _fetch_artifact(self, version: str, host: HostPlatform) -> tuple[Artifact, str]:
+        manifest_url = f"{self.base_url}/{self.product.key}/v{version}/manifest.json"
+        artifact = parse_manifest(
+            _download(manifest_url), requested_version=version, manifest_url=manifest_url, host=host
+        )
+        if artifact.key_id not in self.public_keys:
+            raise GspcManagerError(
+                f"artifact uses unknown signing key {artifact.key_id!r}; "
+                "configure that public key before installing"
+            )
+        return artifact, manifest_url
+
+    def _install(self, destination: Path, artifact: Artifact, version: str, host: HostPlatform) -> Path:
+        archive = _download(artifact.archive_url)
+        signature = _download(artifact.signature_url)
+        verify_ed25519(archive, signature, self.public_keys[artifact.key_id], encoding=artifact.signature_encoding)
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        temporary = Path(tempfile.mkdtemp(prefix=f".{destination.name}-", dir=destination.parent))
+        try:
+            extracted = temporary / "extracted"
+            extracted.mkdir()
+            _safe_extract(archive, artifact.archive_format, extracted)
+            binary_source = _safe_child(extracted, executable_name(artifact.binary, host))
+            if not binary_source.is_file():
+                raise GspcManagerError(f"release archive does not contain declared binary {artifact.binary!r}")
+            # The manifest controls the path inside the archive, but the cache
+            # exposes a stable compiler name to CMake and future cache reads.
+            binary_destination = temporary / "bin" / executable_name(self.product.binary, host)
+            binary_destination.parent.mkdir()
+            shutil.copy2(binary_source, binary_destination)
+            if host.os != "windows":
+                binary_destination.chmod(binary_destination.stat().st_mode | stat.S_IXUSR)
+            self._validate_installed(binary_destination, version)
+            os.replace(temporary, destination)
+            return destination / "bin" / binary_destination.name
+        except Exception:
+            shutil.rmtree(temporary, ignore_errors=True)
+            raise
+
+    @staticmethod
+    def _validate_installed(binary: Path, expected_version: str) -> None:
+        try:
+            result = subprocess.run(
+                [str(binary), "--version"], check=True, text=True, stdout=subprocess.PIPE, stderr=subprocess.STDOUT
+            )
+        except (OSError, subprocess.CalledProcessError) as exc:
+            raise GspcManagerError(f"cannot execute verified GSPC at {binary}: {exc}") from exc
+        tokens = result.stdout.split()
+        if expected_version not in tokens:
+            raise GspcManagerError(
+                f"verified GSPC reports {result.stdout.strip()!r}, expected version {expected_version!r}"
+            )
+
+
+# Compatibility alias for code using the initial single-product API.
+GspcManager = GspManager
+
+
+def load_public_keys(path: Path | None, overrides: list[str]) -> dict[str, str]:
+    keys: dict[str, str] = {}
+    configured_path = path or (Path(os.environ["GSPC_PUBLIC_KEYS_FILE"]) if "GSPC_PUBLIC_KEYS_FILE" in os.environ else None)
+    if configured_path:
+        try:
+            parsed = json.loads(configured_path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as exc:
+            raise GspcManagerError(f"cannot load public keys from {configured_path}: {exc}") from exc
+        if not isinstance(parsed, dict) or not all(isinstance(key, str) and isinstance(value, str) for key, value in parsed.items()):
+            raise GspcManagerError("public-key JSON must be an object mapping key IDs to Base64 keys")
+        keys.update(parsed)
+    for item in overrides:
+        key_id, separator, encoded = item.partition("=")
+        if not separator or not key_id or not encoded:
+            raise GspcManagerError("--public-key must have the form KEY_ID=BASE64_KEY")
+        try:
+            if len(base64.b64decode(encoded, validate=True)) != 32:
+                raise ValueError
+        except ValueError as exc:
+            raise GspcManagerError(f"public key {key_id!r} is not a Base64 Ed25519 public key") from exc
+        keys[key_id] = encoded
+    return keys
+
+
+def _validate_version(version: str) -> None:
+    if not version or version != version.strip() or "/" in version or "\\" in version:
+        raise GspcManagerError(f"invalid GSPC version: {version!r}")
+
+
+def _download(url: str) -> bytes:
+    try:
+        request = Request(url, headers={"User-Agent": "gspc/0.1"})
+        with urlopen(request, timeout=30) as response:
+            return response.read()
+    except OSError as exc:
+        raise GspcManagerError(f"failed to download {url}: {exc}") from exc
+
+
+def _safe_child(root: Path, relative: str) -> Path:
+    path = (root / relative).resolve()
+    resolved_root = root.resolve()
+    if path != resolved_root and resolved_root not in path.parents:
+        raise GspcManagerError(f"unsafe archive path: {relative!r}")
+    return path
+
+
+def _safe_extract(data: bytes, archive_format: str, destination: Path) -> None:
+    if archive_format == "tar.gz":
+        with tarfile.open(fileobj=_BytesReader(data), mode="r:gz") as archive:
+            for member in archive.getmembers():
+                if member.isdir():
+                    _safe_child(destination, member.name).mkdir(parents=True, exist_ok=True)
+                    continue
+                if member.issym() or member.islnk() or not member.isfile():
+                    raise GspcManagerError(f"unsupported member in GSPC archive: {member.name}")
+                target = _safe_child(destination, member.name)
+                target.parent.mkdir(parents=True, exist_ok=True)
+                source = archive.extractfile(member)
+                if source is None:
+                    raise GspcManagerError(f"cannot extract GSPC archive member: {member.name}")
+                with source, target.open("wb") as output:
+                    shutil.copyfileobj(source, output)
+    else:
+        with zipfile.ZipFile(_BytesReader(data)) as archive:
+            for member in archive.infolist():
+                if member.is_dir():
+                    continue
+                target = _safe_child(destination, member.filename)
+                target.parent.mkdir(parents=True, exist_ok=True)
+                with archive.open(member), target.open("wb") as output:
+                    shutil.copyfileobj(member, output)
+
+
+class _BytesReader:
+    """Small seekable adapter keeping archive handling independent of files."""
+
+    def __init__(self, data: bytes) -> None:
+        import io
+
+        self._buffer = io.BytesIO(data)
+
+    def __getattr__(self, name: str):
+        return getattr(self._buffer, name)
+
+
+@contextmanager
+def _cache_lock(lock_path: Path) -> Iterator[None]:
+    deadline = time.monotonic() + 60
+    while True:
+        try:
+            lock_path.mkdir(parents=True)
+            break
+        except FileExistsError:
+            if time.monotonic() >= deadline:
+                raise GspcManagerError(f"timed out waiting for GSPC cache lock {lock_path}")
+            time.sleep(0.1)
+    try:
+        yield
+    finally:
+        lock_path.rmdir()
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="python -m gsp.manager",
+        description="Manage the local cache of signed, pinned esp-gsp-tools releases.",
+    )
+    parser.add_argument("--base-url", help="release server base URL")
+    parser.add_argument("--cache-dir", type=Path, help="directory for verified releases")
+    parser.add_argument("--public-keys-file", type=Path, help="JSON mapping of key IDs to Base64 Ed25519 public keys")
+    parser.add_argument("--public-key", action="append", default=[], metavar="ID=BASE64", help="additional trusted Ed25519 public key; may be repeated")
+    commands = parser.add_subparsers(dest="command", required=True)
+    for name, help_text in (
+        ("install", "install VERSION if it is not already cached"),
+        ("fetch", "download, verify, and cache VERSION for offline use"),
+        ("reinstall", "discard and install VERSION again"),
+        ("path", "print the verified cached executable path for VERSION"),
+        ("remove", "remove the cached VERSION for this host"),
+    ):
+        command = commands.add_parser(name, help=help_text)
+        command.add_argument("first", metavar="VERSION|PRODUCT")
+        command.add_argument("second", metavar="PRODUCT|VERSION")
+    list_command = commands.add_parser("list", help="list cached releases")
+    list_command.add_argument("product", nargs="?", default="gspc", metavar="PRODUCT")
+    return parser
+
+
+def _version_and_product(first: str, second: str) -> tuple[str, str]:
+    """Accept both PRODUCT VERSION and the historical VERSION PRODUCT order."""
+
+    try:
+        get_product(first)
+    except GspManagerError:
+        get_product(second)
+        return first, second
+    return second, first
+
+
+def _normalize_manager_argv(argv: list[str] | None) -> list[str] | None:
+    """Also accept ``gsp.manager PRODUCT COMMAND VERSION`` for convenience."""
+
+    raw = list(argv) if argv is not None else None
+    if raw and raw[0].strip().lower() in {"gspc", "sim"} and len(raw) >= 2:
+        product, command, rest = raw[0], raw[1], raw[2:]
+        if command == "list":
+            return [command, product, *rest]
+        if command in {"install", "fetch", "reinstall", "path", "remove"}:
+            return [command, *rest, product]
+    return raw
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _parser()
+    options = parser.parse_args(_normalize_manager_argv(argv))
+    try:
+        product = options.product if options.command == "list" else _version_and_product(options.first, options.second)[1]
+        manager = GspManager(
+            product=product,
+            base_url=options.base_url,
+            cache_dir=options.cache_dir,
+            public_keys=load_public_keys(options.public_keys_file, options.public_key),
+        )
+        if options.command == "list":
+            for product_name, version, platform_name, executable in manager.list_cached():
+                print(f"{product_name}\t{version}\t{platform_name}\t{executable}")
+            return 0
+        version, _ = _version_and_product(options.first, options.second)
+        if options.command == "path":
+            executable = manager.cached(version)
+            if executable is None:
+                raise GspManagerError(f"{manager.product.display_name} {version} is not cached for this host")
+            print(executable)
+            return 0
+        if options.command == "remove":
+            if not manager.remove(version):
+                raise GspManagerError(f"{manager.product.display_name} {version} is not cached for this host")
+            return 0
+        executable = manager.resolve(version, reinstall=options.command == "reinstall")
+        print(executable)
+        return 0
+    except GspcManagerError as exc:
+        parser.exit(2, f"gsp.manager: error: {exc}\n")
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())