modsmith-cli 0.1.1__py3-none-any.whl

modsmith_cli/commands/update.py

@@ -0,0 +1,324 @@
+"""``modsmith update``: bring an instance's pack and additions up to date."""
+
+from dataclasses import dataclass, replace
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from modsmith.errors import DependencyError, UnresolvedEntriesError, UnsupportedError
+from modsmith.instances import Changes, Instance, InstanceState, Plan
+from modsmith.minecraft import GameDir
+from modsmith.packs import Modpack
+from rich.text import Text
+
+from ..context import AppContext, get
+from ..core.install import (
+    FetchedPack,
+    check_launcher,
+    download_pack,
+    download_sizes,
+    fetch_pack,
+    latest_pack,
+    optional_entries,
+    with_optional,
+)
+from ..core.platforms import explained
+from ..core.records import Record, read_record, write_record
+from ..core.refs import LocalPack
+from ..core.registry import resolve_instance
+from ..errors import report as report_error
+from ..target import DryRun, InstanceName, Yes
+from ..ui import cancellable, confirm, progress, show_changelog, show_plan
+from .install import (
+    AllOptional,
+    From,
+    Optional,
+    Overwrite,
+    choose_optional,
+    loader_label,
+)
+
+CHANGELOG_LINES = 6
+
+
+@dataclass(frozen=True)
+class Choices:
+    """What the player asked ``update`` to do."""
+
+    file: Path | None
+    optional: list[str]
+    all_optional: bool
+    prereleases: bool
+    yes: bool
+
+    @property
+    def reselect(self) -> bool:
+        """Whether the player chose optional files again."""
+        return bool(self.optional) or self.all_optional
+
+
+@dataclass(frozen=True)
+class PackUpdate:
+    """A newer pack, ready to sync into an instance."""
+
+    fetched: FetchedPack
+    pack: Modpack
+    chosen: tuple[str, ...]
+    new_game: bool
+
+
+def _game(pack: Modpack | InstanceState) -> str:
+    return f"Minecraft {pack.minecraft} with " + loader_label(
+        pack.loader_kind, pack.loader_version
+    )
+
+
+def _newer_pack(
+    app: AppContext, record: Record, choices: Choices
+) -> tuple[FetchedPack | None, str]:
+    """Fetch the pack to update to, or explain why there is none."""
+    source = record.source
+    if choices.file is not None:
+        ref = LocalPack(choices.file)
+        fetched = fetch_pack(
+            ref, app.platform, cache_dir=app.paths.cache_dir, allow_prereleases=False
+        )
+        return fetched, ""
+    if source is None:
+        return None, "It has no pack."
+    if source.platform is None or source.project_id is None:
+        return None, "Its pack came from a file. Update it with --file <newer pack>."
+    with (
+        explained(source.platform),
+        app.platform(source.platform) as platform,
+        cancellable() as token,
+        progress(app) as report,
+    ):
+        project, release = latest_pack(
+            platform, source.project_id, allow_prereleases=choices.prereleases
+        )
+        if release.id == source.release_id and not choices.reselect:
+            return None, f"{project.name} is up to date."
+        fetched = download_pack(
+            platform,
+            project,
+            release,
+            app.platform,
+            cache_dir=app.paths.cache_dir,
+            progress=report,
+            cancel=token,
+        )
+        try:
+            changelog = platform.changelog(release)
+        except UnsupportedError:
+            changelog = ""
+    show_changelog(
+        app, f"What changed in {release.name}", changelog, lines=CHANGELOG_LINES
+    )
+    return fetched, ""
+
+
+def _kept_choice(app: AppContext, pack: Modpack, record: Record) -> tuple[str, ...]:
+    """Keep the optional files chosen before, where the new pack still has them."""
+    offered = {entry.path for entry in optional_entries(pack)}
+    kept = tuple(path for path in record.optional if path in offered)
+    gone = len(record.optional) - len(kept)
+    if gone:
+        app.err.print(
+            (
+                "1 optional file you chose is"
+                if gone == 1
+                else f"{gone} optional files you chose are"
+            )
+            + " not in this release. "
+            "Choose again with --optional.",
+            style="yellow",
+        )
+    return kept
+
+
+def _pack_update(
+    app: AppContext, instance: Instance, state: InstanceState, choices: Choices
+) -> PackUpdate | None:
+    """Show what updating the pack would change, if there is a newer one."""
+    record = read_record(instance.path)
+    fetched, reason = _newer_pack(app, record, choices)
+    if fetched is None:
+        app.out.print(Text(reason, style="dim"))
+        return None
+    if choices.reselect:
+        chosen = tuple(
+            choose_optional(
+                app, fetched.pack, choices.optional, choices.all_optional, choices.yes
+            )
+        )
+    else:
+        chosen = _kept_choice(app, fetched.pack, record)
+    pack = with_optional(fetched.pack, chosen)
+    title = f"Update {state.pack_name or 'the pack'} {state.pack_version or ''}"
+    title = f"{title.rstrip()} to {pack.name} {pack.version}"
+    pending = show_plan(app, instance.diff(pack), download_sizes(pack), title=title)
+    new_game = _game(pack) != _game(state)
+    if new_game:
+        app.out.print(f"It moves from {_game(state)} to {_game(pack)}.")
+    if not (pending or new_game):
+        return None
+    return PackUpdate(fetched, pack, chosen, new_game)
+
+
+def _addition_updates(
+    app: AppContext, instance: Instance, state: InstanceState, prereleases: bool
+) -> list[Plan]:
+    """Plan updates for the projects added on their own, platform by platform."""
+    plans: list[Plan] = []
+    for name in sorted({item.platform for item in state.additions}):
+        with explained(name), app.platform(name) as platform:
+            plan = instance.plan_updates(platform, release_only=not prereleases)
+            logs: list[tuple[str, str]] = []
+            for item in plan.additions:
+                try:
+                    release = platform.get_release(item.release_id)
+                    logs.append((release.name, platform.changelog(release)))
+                except UnsupportedError:
+                    continue
+        if not plan.additions:
+            continue
+        plans.append(plan)
+        for title, text in logs:
+            show_changelog(app, f"What changed in {title}", text, lines=CHANGELOG_LINES)
+    return plans
+
+
+def _show_additions(app: AppContext, name: str, plans: list[Plan]) -> bool:
+    changes = Changes(
+        added=tuple(path for plan in plans for path in plan.changes.added),
+        updated=tuple(path for plan in plans for path in plan.changes.updated),
+        removed=tuple(path for plan in plans for path in plan.changes.removed),
+        conflicts=tuple(path for plan in plans for path in plan.changes.conflicts),
+    )
+    sizes = {item.path: item.entry.size for plan in plans for item in plan.additions}
+    pending = show_plan(app, changes, sizes, title=f"Update what you added to {name}")
+    for plan in plans:
+        if not plan.ok:
+            raise DependencyError(plan)
+    return pending
+
+
+def _apply_pack(
+    app: AppContext,
+    instance: Instance,
+    update: PackUpdate,
+    *,
+    overwrite: bool,
+    from_folders: list[Path],
+) -> None:
+    record = read_record(instance.path)
+    game = GameDir(app.config.game_dir)
+    launcher = (
+        check_launcher(game, app.services.launcher_running())
+        if update.new_game and record.profile
+        else None
+    )
+    with cancellable() as token, progress(app) as report:
+        version_id = update.pack.install_game(
+            game, cache_dir=app.paths.cache_dir, progress=report, cancel=token
+        )
+        instance.sync(
+            update.pack,
+            overwrite=overwrite,
+            adopt_from=from_folders,
+            progress=report,
+            cancel=token,
+        )
+    if launcher is not None and record.profile:
+        profile = launcher.profiles().get(record.profile)
+        launcher.add_profile(
+            profile.name if profile else update.pack.name,
+            version_id,
+            instance.path,
+            key=record.profile,
+        )
+    write_record(
+        instance.path,
+        replace(record, source=update.fetched.source, optional=update.chosen),
+    )
+
+
+def update_command(
+    ctx: typer.Context,
+    name: InstanceName = None,
+    pack_only: Annotated[
+        bool, typer.Option("--pack-only", help="Update only the pack.")
+    ] = False,
+    additions_only: Annotated[
+        bool,
+        typer.Option("--additions-only", help="Update only what you added yourself."),
+    ] = False,
+    file: Annotated[
+        Path | None,
+        typer.Option("--file", help="Update the pack from this pack file."),
+    ] = None,
+    optional: Optional = None,
+    all_optional: AllOptional = False,
+    pre: Annotated[
+        bool, typer.Option("--pre", help="Allow alpha and beta releases.")
+    ] = False,
+    overwrite: Overwrite = False,
+    from_folders: From = None,
+    yes: Yes = False,
+    dry_run: DryRun = False,
+) -> None:
+    """Update an instance's pack, and the projects you added to it."""
+    app = get(ctx)
+    instance, state = resolve_instance(name, app.config, app.paths)
+    choices = Choices(
+        file, optional or [], all_optional, pre or app.config.allow_prereleases, yes
+    )
+    pack = None if additions_only else _pack_update(app, instance, state, choices)
+    missing = (
+        [entry for entry in pack.pack.unresolved if entry.wanted("client")]
+        if pack is not None and not from_folders
+        else []
+    )
+    if missing and not dry_run:
+        raise UnresolvedEntriesError(missing)
+    if missing:
+        report_error(
+            UnresolvedEntriesError(missing), app.err, prefix="Before you update: "
+        )
+    plans: list[Plan] = []
+    if pack is not None and pack.new_game and state.additions:
+        app.out.print(
+            Text(
+                "What you added is updated after the pack, the next time you run "
+                "modsmith update.",
+                style="dim",
+            )
+        )
+    elif pack is None or not pack.new_game:
+        plans = (
+            _addition_updates(app, instance, state, choices.prereleases)
+            if not pack_only and state.additions
+            else []
+        )
+    pending = _show_additions(app, instance.path.name, plans) if plans else False
+    if pack is None and not pending:
+        app.out.print(f"Everything in {instance.path.name} is up to date.")
+        return
+    if dry_run:
+        return
+    confirm(app, "Update them?", yes=yes)
+    if pack is not None:
+        _apply_pack(
+            app, instance, pack, overwrite=overwrite, from_folders=from_folders or []
+        )
+    with cancellable() as token, progress(app) as report:
+        for plan in plans:
+            instance.add(
+                plan,
+                overwrite=overwrite,
+                adopt_from=from_folders or (),
+                progress=report,
+                cancel=token,
+            )
+    app.out.print(f"Updated {instance.path.name}.")

modsmith_cli/context.py

@@ -0,0 +1,117 @@
+"""What every command needs: settings, folders, platforms and output."""
+
+import dataclasses
+import os
+import sys
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field
+from enum import StrEnum
+from functools import cached_property
+from typing import cast
+
+import typer
+from modsmith.launcher import is_running
+from modsmith.platforms import Platform
+from rich.console import Console
+
+from .core.config import Config, load_config
+from .core.paths import AppPaths
+from .core.platforms import PlatformOpener, open_platform
+
+
+class ColorMode(StrEnum):
+    """When to use colour."""
+
+    AUTO = "auto"
+    ALWAYS = "always"
+    NEVER = "never"
+
+
+def _interactive() -> bool:
+    """Return whether a person can answer questions on this terminal."""
+    return sys.stdin.isatty() and sys.stdout.isatty()
+
+
+@dataclass(frozen=True)
+class Services:
+    """What the command line gets from the outside world.
+
+    Tests pass their own as the click context's ``obj``.
+
+    Attributes:
+        open_platform: Opens a platform by name.
+        environ: The environment variables, or None for the real ones.
+        interactive: Whether a person can answer questions.
+        launcher_running: Whether the official launcher is open.
+    """
+
+    open_platform: PlatformOpener = open_platform
+    environ: Mapping[str, str] | None = None
+    interactive: Callable[[], bool] = _interactive
+    launcher_running: Callable[[], bool] = is_running
+
+
+def _console(color: ColorMode, *, stderr: bool) -> Console:
+    """Make a console that follows the colour choice and ``NO_COLOR``."""
+    if color == ColorMode.ALWAYS:
+        return Console(stderr=stderr, force_terminal=True)
+    if color == ColorMode.NEVER:
+        return Console(stderr=stderr, no_color=True, color_system=None)
+    return Console(stderr=stderr)
+
+
+@dataclass
+class AppContext:
+    """The state of one command-line run.
+
+    Attributes:
+        paths: The app's folders.
+        services: The outside world.
+        overrides: Settings given as command-line options.
+        verbose: How much detail to show, from ``-v``.
+        color: When to use colour.
+        out: Where results go.
+        err: Where errors, warnings and progress go.
+    """
+
+    paths: AppPaths
+    services: Services
+    overrides: dict[str, object] = field(default_factory=dict[str, object])
+    verbose: int = 0
+    color: ColorMode = ColorMode.AUTO
+    out: Console = field(init=False)
+    err: Console = field(init=False)
+
+    def __post_init__(self) -> None:
+        self.out = _console(self.color, stderr=False)
+        self.err = _console(self.color, stderr=True)
+
+    @property
+    def environ(self) -> Mapping[str, str]:
+        """The environment variables."""
+        return (
+            self.services.environ if self.services.environ is not None else os.environ
+        )
+
+    @cached_property
+    def config(self) -> Config:
+        """The settings in effect. Read on first use, so ``config`` can fix bad ones.
+
+        Raises:
+            AppError: A setting is invalid.
+        """
+        config = load_config(self.paths, self.environ)
+        return dataclasses.replace(config, **self.overrides)
+
+    def platform(self, name: str) -> Platform:
+        """Open a platform by name.
+
+        Raises:
+            AppError: The platform needs a key that is not set.
+        """
+        return self.services.open_platform(name, self.config)
+
+
+def get(ctx: typer.Context) -> AppContext:
+    """Return the run's state from any command's context."""
+    return cast(AppContext, ctx.find_root().obj)

modsmith_cli/core/__init__.py

@@ -0,0 +1,5 @@
+"""The command line's work, kept apart from how it is shown.
+
+Nothing here prints or asks questions. Functions take what they need as
+arguments and return results or raise `AppError`, so any front end can use them.
+"""

modsmith_cli/core/config.py

@@ -0,0 +1,243 @@
+"""The app's settings: defaults, then ``config.toml``, then environment variables.
+
+Command-line options override all three, in the front end.
+"""
+
+import os
+import tomllib
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, fields
+from pathlib import Path
+from typing import Any
+
+import tomli_w
+from modsmith.minecraft import GameDir
+
+from .errors import AppError
+from .paths import AppPaths
+
+PLATFORMS = ("modrinth", "curseforge")
+TRUE = {"true", "yes", "on", "1"}
+FALSE = {"false", "no", "off", "0"}
+
+
+@dataclass(frozen=True)
+class Config:
+    """The settings in effect.
+
+    Attributes:
+        instances_dir: Where new instances are created.
+        game_dir: The official launcher's game directory.
+        curseforge_api_key: The key for the CurseForge API, or None.
+        default_platform: Where to look when a project names no platform.
+        allow_prereleases: Whether alpha and beta releases may be chosen.
+    """
+
+    instances_dir: Path
+    game_dir: Path
+    curseforge_api_key: str | None = None
+    default_platform: str = "modrinth"
+    allow_prereleases: bool = False
+
+
+@dataclass(frozen=True)
+class Setting:
+    """How one setting is described, read and checked.
+
+    Attributes:
+        key: Its name in ``config.toml``.
+        description: What it does.
+        parse: Turns text into the setting's value, or raises `AppError`.
+        variable: The environment variable that overrides it, or None.
+        secret: Whether to hide its value when it is shown.
+    """
+
+    key: str
+    description: str
+    parse: Callable[[str], Any]
+    variable: str | None = None
+    secret: bool = False
+
+
+def _path(text: str) -> Path:
+    if not text.strip():
+        raise AppError("A path cannot be empty.")
+    return Path(text).expanduser()
+
+
+def _boolean(text: str) -> bool:
+    value = text.strip().lower()
+    if value in TRUE:
+        return True
+    if value in FALSE:
+        return False
+    raise AppError(f"{text!r} is not true or false.")
+
+
+def _platform(text: str) -> str:
+    value = text.strip().lower()
+    if value not in PLATFORMS:
+        raise AppError(
+            f"{text!r} is not a platform.", hint="Use modrinth or curseforge."
+        )
+    return value
+
+
+def _secret(text: str) -> str:
+    if not text.strip():
+        raise AppError("The key cannot be empty.")
+    return text.strip()
+
+
+SETTINGS = {
+    item.key: item
+    for item in [
+        Setting(
+            "instances_dir",
+            "Where new instances are created",
+            _path,
+            "MODSMITH_INSTANCES_DIR",
+        ),
+        Setting(
+            "game_dir",
+            "The official launcher's game directory",
+            _path,
+            "MODSMITH_GAME_DIR",
+        ),
+        Setting(
+            "curseforge_api_key",
+            "Your CurseForge API key",
+            _secret,
+            "CURSEFORGE_API_KEY",
+            secret=True,
+        ),
+        Setting(
+            "default_platform",
+            "Where to look when a project names no platform",
+            _platform,
+        ),
+        Setting(
+            "allow_prereleases",
+            "Whether alpha and beta releases may be chosen",
+            _boolean,
+        ),
+    ]
+}
+assert set(SETTINGS) == {item.name for item in fields(Config)}
+
+
+def setting(key: str) -> Setting:
+    """Return a setting by name.
+
+    Raises:
+        AppError: There is no such setting.
+    """
+    try:
+        return SETTINGS[key]
+    except KeyError:
+        known = ", ".join(SETTINGS)
+        raise AppError(
+            f"There is no setting called {key!r}.", hint=f"Settings: {known}."
+        ) from None
+
+
+def read_file(paths: AppPaths) -> dict[str, Any]:
+    """Return the settings saved in ``config.toml``, as written.
+
+    Raises:
+        AppError: The file is not valid TOML.
+    """
+    try:
+        with paths.config_file.open("rb") as file:
+            return tomllib.load(file)
+    except FileNotFoundError:
+        return {}
+    except tomllib.TOMLDecodeError as e:
+        raise AppError(
+            f"{paths.config_file} is not valid TOML: {e}",
+            hint="Fix or delete the file.",
+        ) from e
+
+
+def load_config(paths: AppPaths, environ: Mapping[str, str] = os.environ) -> Config:
+    """Work out the settings in effect.
+
+    Args:
+        paths: The app's folders.
+        environ: The environment variables.
+
+    Returns:
+        The settings.
+
+    Raises:
+        AppError: A saved or environment value is invalid.
+    """
+    values: dict[str, Any] = {
+        "instances_dir": paths.default_instances_dir,
+        "game_dir": GameDir.default().path,
+    }
+    for key, raw in read_file(paths).items():
+        if key in SETTINGS:
+            values[key] = _checked(
+                key,
+                str(raw).lower() if isinstance(raw, bool) else str(raw),
+                f"{paths.config_file}",
+            )
+    for key, item in SETTINGS.items():
+        raw = environ.get(item.variable) if item.variable else None
+        if raw:
+            values[key] = _checked(key, raw, f"${item.variable}")
+    return Config(**values)
+
+
+def _checked(key: str, raw: str, source: str) -> Any:
+    """Parse a value, saying where a bad one came from."""
+    try:
+        return SETTINGS[key].parse(raw)
+    except AppError as e:
+        raise AppError(f"{key} in {source}: {e.message}", hint=e.hint) from e
+
+
+def sources(paths: AppPaths, environ: Mapping[str, str] = os.environ) -> dict[str, str]:
+    """Return where each setting's value comes from.
+
+    Each is ``default``, ``config file`` or ``$VARIABLE``.
+    """
+    saved = read_file(paths)
+    found: dict[str, str] = {}
+    for key, item in SETTINGS.items():
+        if item.variable and environ.get(item.variable):
+            found[key] = f"${item.variable}"
+        elif key in saved:
+            found[key] = "config file"
+        else:
+            found[key] = "default"
+    return found
+
+
+def save_setting(paths: AppPaths, key: str, raw: str | None) -> None:
+    """Save a setting to ``config.toml``, or remove it when ``raw`` is None.
+
+    Raises:
+        AppError: The setting does not exist or the value is invalid.
+    """
+    item = setting(key)
+    saved = read_file(paths)
+    if raw is None:
+        saved.pop(key, None)
+    else:
+        value = item.parse(raw)
+        saved[key] = str(value) if isinstance(value, Path) else value
+    paths.config_file.parent.mkdir(parents=True, exist_ok=True)
+    paths.config_file.write_text(tomli_w.dumps(saved), encoding="utf-8")
+
+
+def shown(key: str, value: Any) -> str:
+    """Format a setting's value for display, hiding secrets."""
+    if value is None:
+        return "not set"
+    if SETTINGS[key].secret:
+        return "set (hidden)"
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    return str(value)