modsmith-cli 0.1.1__py3-none-any.whl

modsmith_cli/core/contents.py

@@ -0,0 +1,68 @@
+"""Find the files an instance holds by the names players use for them."""
+
+from collections.abc import Iterable
+
+from modsmith import metadata
+from modsmith.instances import ContentFile, Instance
+
+from .errors import AppError
+
+DISABLED = ".disabled"
+
+
+def _file_name(path: str) -> str:
+    return path.rsplit("/", 1)[-1].lower()
+
+
+def _declared(instance: Instance, item: ContentFile) -> set[str]:
+    """Return the id and name a file declares about itself, in lower case."""
+    try:
+        info = metadata.read(instance.path / item.location)
+    except OSError:
+        return set()
+    if info is None:
+        return set()
+    return {text.lower() for text in (info.id, info.name) if text}
+
+
+def _matches(
+    instance: Instance, contents: Iterable[ContentFile], name: str
+) -> list[ContentFile]:
+    """Return the files a name means, trying cheap matches before reading files."""
+    wanted = name.lower().removesuffix(DISABLED)
+    hits = [
+        item
+        for item in contents
+        if (item.addition is not None and item.addition.matches(name))
+        or item.path.lower() == wanted
+        or _file_name(item.path) == wanted
+    ]
+    if hits:
+        return hits
+    return [item for item in contents if wanted in _declared(instance, item)]
+
+
+def find_contents(instance: Instance, names: Iterable[str]) -> list[ContentFile]:
+    """Match each name to one mod, resource pack or shader pack in the instance.
+
+    A name can be an added project's id or slug, a path such as
+    ``mods/sodium.jar``, a file name with or without ``.disabled``, or the id
+    or name a mod declares about itself, such as ``iris``.
+
+    Raises:
+        AppError: A name matches nothing, or more than one file.
+    """
+    contents = instance.contents()
+    found: list[ContentFile] = []
+    for name in names:
+        hits = _matches(instance, contents, name)
+        if not hits:
+            raise AppError(
+                f"Nothing in {instance.path.name} is called {name!r}.",
+                hint=f"See what it holds with: modsmith show {instance.path.name}",
+            )
+        if len(hits) > 1:
+            listed = ", ".join(item.path for item in hits)
+            raise AppError(f"{name!r} could mean {listed}.", hint="Use the full path.")
+        found.append(hits[0])
+    return list(dict.fromkeys(found))

modsmith_cli/core/errors.py

@@ -0,0 +1,19 @@
+"""Errors the app reports to the player."""
+
+
+class AppError(Exception):
+    """Something the player can fix, with a hint on how.
+
+    Args:
+        message: What went wrong.
+        hint: What to do about it, or None.
+
+    Attributes:
+        message: What went wrong.
+        hint: What to do about it, or None.
+    """
+
+    def __init__(self, message: str, hint: str | None = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.hint = hint

modsmith_cli/core/install.py

@@ -0,0 +1,244 @@
+"""Getting a pack ready to install, and adding it to the official launcher."""
+
+import dataclasses
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass
+from pathlib import Path
+
+from modsmith.errors import LauncherError, ModsmithError
+from modsmith.launcher import Launcher, icon_data_uri
+from modsmith.minecraft import GameDir
+from modsmith.net import Session
+from modsmith.packs import Modpack, PackEntry, load
+from modsmith.platforms import Platform, Project, Release
+from modsmith.progress import CancelToken, ProgressCallback
+
+from .errors import AppError
+from .names import name_from
+from .records import PackSource
+from .refs import LocalPack, ProjectRef
+
+PROFILE_PREFIX = "modsmith-"
+# The launcher shows PNG and JPEG icons; other formats are left out.
+ICON_TYPES = ("image/png", "image/jpeg")
+
+
+@dataclass(frozen=True)
+class FetchedPack:
+    """A pack read and ready to install.
+
+    Attributes:
+        pack: The pack, with downloads looked up where its format needs it.
+        source: Where it came from.
+        project: Its project on a platform, or None for a local file.
+    """
+
+    pack: Modpack
+    source: PackSource
+    project: Project | None = None
+
+
+def _resolved(pack: Modpack, open_platform: Callable[[str], Platform]) -> Modpack:
+    """Look up downloads for a CurseForge pack, whose files are named by id."""
+    if pack.format != "curseforge":
+        return pack
+    with open_platform("curseforge") as platform:
+        return platform.resolve(pack)
+
+
+def latest_pack(
+    platform: Platform, name: str, *, allow_prereleases: bool
+) -> tuple[Project, Release]:
+    """Find a modpack project and its newest release.
+
+    Raises:
+        AppError: The project is not a modpack, or has no release.
+        NetworkError: The platform could not be reached.
+    """
+    project = platform.get_project(name, project_type="modpack")
+    if project.project_type != "modpack":
+        raise AppError(
+            f"{project.name} is a {project.project_type}, not a modpack.",
+            hint=f"Add it to an instance with: modsmith add <instance> "
+            f"{platform.name}:{name}",
+        )
+    release = platform.latest_release(project, release_only=not allow_prereleases)
+    if release is None:
+        raise AppError(
+            f"{project.name} has no release to install.",
+            hint="Alpha and beta releases count if you run: "
+            "modsmith config set allow_prereleases true",
+        )
+    return project, release
+
+
+def download_pack(
+    platform: Platform,
+    project: Project,
+    release: Release,
+    open_platform: Callable[[str], Platform],
+    *,
+    cache_dir: Path,
+    progress: ProgressCallback | None = None,
+    cancel: CancelToken | None = None,
+) -> FetchedPack:
+    """Download a pack release into the cache and read it.
+
+    Raises:
+        PackError: The file is not a valid pack.
+        NetworkError: A platform could not be reached.
+    """
+    folder = cache_dir / "packs" / platform.name
+    path = platform.fetch(release, folder, progress=progress, cancel=cancel)
+    pack = _resolved(load(path), open_platform)
+    return FetchedPack(pack, PackSource(platform.name, project.id, release.id), project)
+
+
+def fetch_pack(
+    ref: ProjectRef | LocalPack,
+    open_platform: Callable[[str], Platform],
+    *,
+    cache_dir: Path,
+    allow_prereleases: bool,
+    progress: ProgressCallback | None = None,
+    cancel: CancelToken | None = None,
+) -> FetchedPack:
+    """Read a local pack, or download a platform pack's newest release.
+
+    Args:
+        ref: The pack.
+        open_platform: Opens a platform by name.
+        cache_dir: Where downloaded packs are kept.
+        allow_prereleases: Whether an alpha or beta release may be chosen.
+        progress: Receives download updates.
+        cancel: Stops the download.
+
+    Returns:
+        The pack.
+
+    Raises:
+        AppError: The project is not a modpack, or has no release.
+        PackError: The file is not a valid pack.
+        NetworkError: A platform could not be reached.
+    """
+    if isinstance(ref, LocalPack):
+        pack = load(ref.path)
+        source = PackSource(file=str(ref.path.resolve()))
+        return FetchedPack(_resolved(pack, open_platform), source)
+    with open_platform(ref.platform) as platform:
+        project, release = latest_pack(
+            platform, ref.name, allow_prereleases=allow_prereleases
+        )
+        return download_pack(
+            platform,
+            project,
+            release,
+            open_platform,
+            cache_dir=cache_dir,
+            progress=progress,
+            cancel=cancel,
+        )
+
+
+def optional_entries(pack: Modpack) -> list[PackEntry]:
+    """Return the files a pack lets the player choose to install."""
+    return [
+        entry
+        for entry in pack.entries
+        if entry.path and entry.support("client") == "optional"
+    ]
+
+
+def match_optional(pack: Modpack, patterns: Iterable[str]) -> list[str]:
+    """Find the optional files whose paths contain each pattern.
+
+    Raises:
+        AppError: A pattern matches no optional file.
+    """
+    options = [entry.path for entry in optional_entries(pack) if entry.path]
+    chosen: list[str] = []
+    for pattern in patterns:
+        hits = [path for path in options if pattern.lower() in path.lower()]
+        if not hits:
+            listed = ", ".join(options) or "none"
+            raise AppError(
+                f"No optional file matches {pattern!r}.",
+                hint=f"The optional files are: {listed}.",
+            )
+        chosen.extend(hits)
+    return list(dict.fromkeys(chosen))
+
+
+def with_optional(pack: Modpack, chosen: Iterable[str]) -> Modpack:
+    """Return the pack with the chosen optional files made part of the install."""
+    wanted = set(chosen)
+    entries = tuple(
+        dataclasses.replace(entry, client="required")
+        if entry.path in wanted and entry.support("client") == "optional"
+        else entry
+        for entry in pack.entries
+    )
+    return pack.with_entries(entries)
+
+
+def download_sizes(pack: Modpack) -> dict[str, int | None]:
+    """Return each file's download size, for a plan's summary."""
+    return {entry.path: entry.size for entry in pack.entries if entry.path}
+
+
+def check_launcher(game: GameDir, running: bool) -> Launcher:
+    """Make sure the official launcher's profiles can be changed now.
+
+    Raises:
+        AppError: The launcher is open, or has never run with this game
+            directory.
+    """
+    if running:
+        raise AppError(
+            "Close the official launcher first.",
+            hint="It saves its own list of installations when it closes, "
+            "which would undo this change.",
+        )
+    launcher = Launcher(game)
+    try:
+        launcher.profiles()
+    except LauncherError as e:
+        raise AppError(
+            f"The official launcher has not been set up in {game.path}.",
+            hint="Start the official launcher once and close it, then try again. "
+            "If you use another game directory, set it with: "
+            "modsmith config set game_dir <folder>",
+        ) from e
+    return launcher
+
+
+def profile_name(launcher: Launcher, wanted: str, key: str, instance: str) -> str:
+    """Return a launcher name for an installation that no other one has.
+
+    A second instance of the same pack is told apart by its instance name, as
+    in ``Fabulously Optimized (fo-2)``.
+    """
+    taken = {
+        profile.name for other, profile in launcher.profiles().items() if other != key
+    }
+    return wanted if wanted not in taken else f"{wanted} ({instance})"
+
+
+def profile_key(name: str) -> str:
+    """Return the launcher profile key for an instance."""
+    return PROFILE_PREFIX + name_from(name)
+
+
+def project_icon(project: Project | None) -> str | None:
+    """Download a project's icon as a data URI, or return None if there is none."""
+    if project is None or not project.icon_url:
+        return None
+    try:
+        with Session() as session:
+            response = session.request("GET", project.icon_url)
+    except ModsmithError:
+        return None
+    kind = response.headers.get("Content-Type", "").split(";")[0].strip()
+    if kind not in ICON_TYPES:
+        return None
+    return icon_data_uri(response.content, kind)

modsmith_cli/core/names.py

@@ -0,0 +1,30 @@
+"""Instance names: what is allowed, and a default made from a pack's name."""
+
+import re
+
+from .errors import AppError
+
+NAME = re.compile(r"^[A-Za-z0-9][A-Za-z0-9 ._-]{0,63}$")
+
+
+def check_name(name: str) -> str:
+    """Return a valid instance name unchanged.
+
+    Raises:
+        AppError: The name could not be a folder name on every system.
+    """
+    if not NAME.match(name) or name.endswith((" ", ".")):
+        raise AppError(
+            f"{name!r} cannot be an instance name.",
+            hint=(
+                "Use up to 64 letters, digits, spaces, dots, dashes and "
+                "underscores, starting with a letter or digit."
+            ),
+        )
+    return name
+
+
+def name_from(text: str) -> str:
+    """Make an instance name from a pack's name, such as ``fabulously-optimized``."""
+    slug = re.sub(r"[^a-z0-9]+", "-", text.lower()).strip("-")[:64].strip("-")
+    return slug or "instance"

modsmith_cli/core/paths.py

@@ -0,0 +1,63 @@
+"""Where the app keeps its configuration, data and caches."""
+
+import os
+import sys
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+
+from platformdirs import user_cache_path, user_config_path, user_data_path
+
+HOME_VARIABLE = "MODSMITH_HOME"
+
+
+@dataclass(frozen=True)
+class AppPaths:
+    """The app's own folders.
+
+    Attributes:
+        config_dir: Holds ``config.toml``.
+        data_dir: Holds instances and the list of instances kept elsewhere.
+        cache_dir: Holds downloaded Java runtimes and loader installers.
+    """
+
+    config_dir: Path
+    data_dir: Path
+    cache_dir: Path
+
+    @property
+    def config_file(self) -> Path:
+        """The configuration file."""
+        return self.config_dir / "config.toml"
+
+    @property
+    def default_instances_dir(self) -> Path:
+        """Where instances go unless the configuration says otherwise."""
+        return self.data_dir / "instances"
+
+    @property
+    def external_file(self) -> Path:
+        """The list of instances outside the instances folder."""
+        return self.data_dir / "external.json"
+
+    @classmethod
+    def from_environment(cls, environ: Mapping[str, str] = os.environ) -> "AppPaths":
+        """Use ``MODSMITH_HOME`` if it is set, and the system's usual folders if not.
+
+        Args:
+            environ: The environment variables.
+
+        Returns:
+            The folders.
+        """
+        home = environ.get(HOME_VARIABLE)
+        if home:
+            root = Path(home).expanduser()
+            return cls(root, root, root / "cache")
+        # Linux folders are lowercase by convention.
+        name = "modsmith" if sys.platform.startswith("linux") else "Modsmith"
+        return cls(
+            user_config_path(name, appauthor=False, roaming=True),
+            user_data_path(name, appauthor=False),
+            user_cache_path(name, appauthor=False),
+        )

modsmith_cli/core/platforms.py

@@ -0,0 +1,98 @@
+"""Open the platforms that projects come from."""
+
+from collections.abc import Callable, Collection, Generator
+from contextlib import contextmanager
+
+from modsmith.errors import NetworkError, PlatformError
+from modsmith.platforms import CurseForge, Modrinth, Platform
+
+from .. import __version__
+from .config import Config
+from .errors import AppError
+
+USER_AGENT = f"modsmith-cli/{__version__} (+https://github.com/ModsmithMC/modsmith-cli)"
+CURSEFORGE_CONSOLE = "https://console.curseforge.com"
+# CurseForge answers these when the key is wrong.
+REJECTED = (401, 403)
+NOT_FOUND = 404
+TITLES = {"modrinth": "Modrinth", "curseforge": "CurseForge"}
+
+# Opens a platform by name. Tests pass one that serves a catalogue from memory.
+PlatformOpener = Callable[[str, Config], Platform]
+
+
+def open_platform(name: str, config: Config) -> Platform:
+    """Open a platform. Close it when done, or use it as a context manager.
+
+    Args:
+        name: ``modrinth`` or ``curseforge``.
+        config: The settings, which hold the CurseForge key.
+
+    Returns:
+        The platform.
+
+    Raises:
+        AppError: CurseForge has no key, or the name is unknown.
+    """
+    if name == "modrinth":
+        return Modrinth(USER_AGENT)
+    if name == "curseforge":
+        if not config.curseforge_api_key:
+            raise AppError(
+                "CurseForge needs an API key.",
+                hint=(
+                    f"Get one at {CURSEFORGE_CONSOLE}, then run: "
+                    "modsmith config set curseforge_api_key <key>"
+                ),
+            )
+        return CurseForge(config.curseforge_api_key)
+    raise AppError(f"{name!r} is not a platform.", hint="Use modrinth or curseforge.")
+
+
+def platform_title(name: str) -> str:
+    """Return a platform's name as people write it, such as ``CurseForge``."""
+    return TITLES.get(name, name)
+
+
+@contextmanager
+def explained(name: str, wanted: Collection[str] = ()) -> Generator[None]:
+    """Turn a platform's refusal into an `AppError` that says what to fix.
+
+    Args:
+        name: The platform in use.
+        wanted: The projects asked for, to name the one the platform lacks.
+
+    Raises:
+        AppError: CurseForge rejected the API key, or the platform has no
+            project by one of the wanted names.
+    """
+    try:
+        yield
+    except NetworkError as e:
+        if name == "curseforge" and e.status in REJECTED:
+            raise AppError(
+                "CurseForge rejected the API key.",
+                hint=(
+                    "Set it again: modsmith config set curseforge_api_key '<key>'. "
+                    "In PowerShell, use single quotes, because $ starts a "
+                    "variable inside double quotes."
+                ),
+            ) from e
+        if e.status == NOT_FOUND and wanted:
+            raise _unknown(name, wanted, str(e)) from e
+        raise
+    except PlatformError as e:
+        # CurseForge finds slugs by searching, and says so when none matches.
+        if any(item in str(e) for item in wanted):
+            raise _unknown(name, wanted, str(e)) from e
+        raise
+
+
+def _unknown(name: str, wanted: Collection[str], message: str) -> AppError:
+    """Say which of the wanted projects a platform does not have."""
+    unknown = [item for item in wanted if item in message] or list(wanted)
+    names = " or ".join(repr(item) for item in unknown)
+    return AppError(
+        f"{platform_title(name)} has no project called {names}.",
+        hint=f"Look for it with: modsmith search {unknown[0]} --platform {name}",
+    )

modsmith_cli/core/records.py

@@ -0,0 +1,73 @@
+"""What the app remembers about each instance, next to the library's own state."""
+
+import json
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any
+
+from .errors import AppError
+
+RECORD_FILE = ".modsmith/app.json"
+
+
+@dataclass(frozen=True)
+class PackSource:
+    """Where an instance's pack came from, so it can be updated.
+
+    Attributes:
+        platform: The platform's name, or None for a local file.
+        project_id: The pack's project id on that platform.
+        release_id: The installed release's id on that platform.
+        file: The local pack file, or None for a platform pack.
+    """
+
+    platform: str | None = None
+    project_id: str | None = None
+    release_id: str | None = None
+    file: str | None = None
+
+
+@dataclass(frozen=True)
+class Record:
+    """What the app remembers about one instance.
+
+    Attributes:
+        source: Where its pack came from, or None if it has no pack.
+        profile: The key of its official launcher profile, or None.
+        optional: The optional pack files the player chose.
+    """
+
+    source: PackSource | None = None
+    profile: str | None = None
+    optional: tuple[str, ...] = field(default_factory=tuple[str, ...])
+
+
+def read_record(instance: Path) -> Record:
+    """Read an instance's record, or an empty one if it has none.
+
+    Raises:
+        AppError: The record is corrupt.
+    """
+    path = instance / RECORD_FILE
+    try:
+        data: dict[str, Any] = json.loads(path.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        return Record()
+    except ValueError as e:
+        raise AppError(f"{path} is corrupt: {e}") from e
+    try:
+        source = data.get("source")
+        return Record(
+            source=PackSource(**source) if source else None,
+            profile=data.get("profile"),
+            optional=tuple(data.get("optional", ())),
+        )
+    except TypeError as e:
+        raise AppError(f"{path} is corrupt: {e}") from e
+
+
+def write_record(instance: Path, record: Record) -> None:
+    """Save an instance's record."""
+    path = instance / RECORD_FILE
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(asdict(record), indent=2), encoding="utf-8")

modsmith_cli/core/refs.py

@@ -0,0 +1,96 @@
+"""Read how a player names a project or a pack.
+
+``sodium`` uses the default platform, ``curseforge:238222`` or ``modrinth:iris``
+names one, a project page's address works too, and a path to a ``.mrpack`` or
+``.zip`` file means a local pack.
+"""
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from .config import PLATFORMS
+from .errors import AppError
+
+PACK_SUFFIXES = (".mrpack", ".zip")
+ADDRESSES = [
+    ("modrinth", re.compile(r"^https?://(?:www\.)?modrinth\.com/[a-z]+/([^/?#]+)")),
+    (
+        "curseforge",
+        re.compile(r"^https?://(?:www\.)?curseforge\.com/minecraft/[a-z-]+/([^/?#]+)"),
+    ),
+]
+
+
+@dataclass(frozen=True)
+class ProjectRef:
+    """A project on a platform.
+
+    Attributes:
+        platform: The platform's name.
+        name: The project's id or slug.
+    """
+
+    platform: str
+    name: str
+
+    def __str__(self) -> str:
+        return f"{self.platform}:{self.name}"
+
+
+@dataclass(frozen=True)
+class LocalPack:
+    """A pack file on this computer.
+
+    Attributes:
+        path: The file.
+    """
+
+    path: Path
+
+
+def parse_project(text: str, default_platform: str) -> ProjectRef:
+    """Read a project name, a ``platform:name`` pair or a project's address.
+
+    Args:
+        text: What the player typed.
+        default_platform: The platform for a bare name.
+
+    Returns:
+        The project.
+
+    Raises:
+        AppError: The text is empty or names an unknown platform.
+    """
+    text = text.strip()
+    for platform, pattern in ADDRESSES:
+        match = pattern.match(text)
+        if match:
+            return ProjectRef(platform, match[1])
+    platform, separator, name = text.partition(":")
+    if not separator:
+        platform, name = default_platform, text
+    platform = platform.lower()
+    if platform not in PLATFORMS:
+        raise AppError(
+            f"{platform!r} is not a platform.",
+            hint="Write modrinth:<name> or curseforge:<name>.",
+        )
+    if not name:
+        raise AppError("A project needs a name.")
+    return ProjectRef(platform, name)
+
+
+def parse_pack(text: str, default_platform: str) -> ProjectRef | LocalPack:
+    """Read a pack: a local file, or a project as `parse_project` reads it.
+
+    Raises:
+        AppError: The text names a pack file that does not exist, or is not a
+            project.
+    """
+    path = Path(text).expanduser()
+    if path.suffix.lower() in PACK_SUFFIXES:
+        if not path.is_file():
+            raise AppError(f"{path} does not exist.")
+        return LocalPack(path)
+    return parse_project(text, default_platform)