modsmith-cli 0.1.1__py3-none-any.whl

modsmith_cli/__init__.py

@@ -0,0 +1,8 @@
+"""Modsmith's command line: modpacks, mods and packs for the official Minecraft launcher."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("modsmith-cli")
+except PackageNotFoundError:
+    __version__ = "0.0.0"

modsmith_cli/__main__.py

@@ -0,0 +1,6 @@
+"""Run the command line with ``python -m modsmith_cli``."""
+
+from modsmith_cli.app import main
+
+if __name__ == "__main__":
+    main()

modsmith_cli/app.py

@@ -0,0 +1,224 @@
+"""The ``modsmith`` command and its global options."""
+
+import io
+import logging
+import sys
+from pathlib import Path
+from typing import Annotated, TextIO
+
+import typer
+from rich.logging import RichHandler
+
+from . import __version__
+from .commands.config import config_app
+from .commands.contents import (
+    add_command,
+    adopt_command,
+    disable_command,
+    enable_command,
+    pin_command,
+    remove_command,
+    show_command,
+    unpin_command,
+)
+from .commands.discovery import info_command, loaders_command
+from .commands.install import create_command, install_command
+from .commands.instance import delete_command, import_command, move_command
+from .commands.list import list_command
+from .commands.search import search_command
+from .commands.update import update_command
+from .context import AppContext, ColorMode, Services
+from .core.paths import AppPaths
+from .errors import reported
+from .target import examples
+
+app = typer.Typer(
+    help=(
+        "Install Minecraft modpacks, mods, resource packs and shaders "
+        "for the official launcher."
+    ),
+    no_args_is_help=True,
+    pretty_exceptions_enable=False,
+    rich_markup_mode=None,
+)
+
+
+def _show_version(value: bool) -> None:
+    if value:
+        typer.echo(f"modsmith {__version__}")
+        raise typer.Exit
+
+
+@app.callback()
+def root(
+    ctx: typer.Context,
+    instances_dir: Annotated[
+        Path | None,
+        typer.Option("--instances-dir", help="Use this instances folder for this run."),
+    ] = None,
+    game_dir: Annotated[
+        Path | None,
+        typer.Option("--game-dir", help="Use this game directory for this run."),
+    ] = None,
+    verbose: Annotated[
+        int,
+        typer.Option(
+            "--verbose", "-v", count=True, help="Show more detail. Repeat for more."
+        ),
+    ] = 0,
+    color: Annotated[
+        ColorMode,
+        typer.Option("--color", help="When to use colour. NO_COLOR also turns it off."),
+    ] = ColorMode.AUTO,
+    version: Annotated[
+        bool,
+        typer.Option(
+            "--version",
+            callback=_show_version,
+            is_eager=True,
+            help="Show the version and exit.",
+        ),
+    ] = False,
+) -> None:
+    """Set up the run before any command."""
+    services = ctx.obj if isinstance(ctx.obj, Services) else Services()
+    environ = services.environ
+    paths = (
+        AppPaths.from_environment()
+        if environ is None
+        else AppPaths.from_environment(environ)
+    )
+    overrides: dict[str, object] = {}
+    if instances_dir is not None:
+        overrides["instances_dir"] = instances_dir.expanduser()
+    if game_dir is not None:
+        overrides["game_dir"] = game_dir.expanduser()
+    context = AppContext(paths, services, overrides, verbose=verbose, color=color)
+    if verbose:
+        level = logging.INFO if verbose == 1 else logging.DEBUG
+        handler = RichHandler(console=context.err, show_path=False)
+        logging.basicConfig(level=level, handlers=[handler], force=True)
+    ctx.obj = context
+
+
+app.command(
+    "install",
+    epilog=examples(
+        "modsmith install fabulously-optimized",
+        "modsmith install curseforge:all-the-mods-9 --name atm9",
+        "modsmith install Downloads/pack.mrpack --all-optional",
+        "modsmith install curseforge:some-pack --from Downloads/manual",
+    ),
+)(reported(install_command))
+app.command(
+    "create",
+    epilog=examples(
+        "modsmith create vanilla --minecraft 1.21.1",
+        "modsmith create modded --minecraft 1.21.1 --loader fabric",
+        "modsmith create old --minecraft 1.20.1 --loader forge --loader-version 47.3.0",
+    ),
+)(reported(create_command))
+app.command("list")(reported(list_command))
+app.command(
+    "search",
+    epilog=examples(
+        "modsmith search sodium",
+        'modsmith search "fabulously optimized" --type modpack',
+        "modsmith search shaders --type shader --sort downloads",
+        "modsmith search jei --platform all --minecraft 1.20.1 --loader forge",
+    ),
+)(reported(search_command))
+app.command("show", epilog=examples("modsmith show", "modsmith show survival"))(
+    reported(show_command)
+)
+app.command(
+    "add",
+    epilog=examples(
+        "modsmith add survival sodium lithium",
+        "modsmith add survival curseforge:jei",
+        "modsmith add survival complementary-reimagined --type shader",
+    ),
+)(reported(add_command))
+app.command(
+    "remove",
+    epilog=examples(
+        "modsmith remove survival sodium", "modsmith remove iris --keep-deps"
+    ),
+)(reported(remove_command))
+app.command("enable", epilog=examples("modsmith enable survival sodium"))(
+    reported(enable_command)
+)
+app.command(
+    "disable",
+    epilog=examples(
+        "modsmith disable survival sodium",
+        "modsmith disable survival mods/OptiFine.jar",
+    ),
+)(reported(disable_command))
+app.command("pin", epilog=examples("modsmith pin survival sodium"))(
+    reported(pin_command)
+)
+app.command("unpin", epilog=examples("modsmith unpin survival sodium"))(
+    reported(unpin_command)
+)
+app.command(
+    "adopt",
+    epilog=examples("modsmith adopt survival", "modsmith adopt survival -p modrinth"),
+)(reported(adopt_command))
+app.command(
+    "info",
+    epilog=examples(
+        "modsmith info sodium",
+        "modsmith info curseforge:jei --minecraft 1.20.1 --loader forge",
+        "modsmith info fabulously-optimized --type modpack",
+    ),
+)(reported(info_command))
+app.command(
+    "loaders",
+    epilog=examples(
+        "modsmith loaders fabric 1.21.1", "modsmith loaders forge 1.20.1 --all"
+    ),
+)(reported(loaders_command))
+app.command(
+    "update",
+    epilog=examples(
+        "modsmith update survival",
+        "modsmith update survival --dry-run",
+        "modsmith update survival --pack-only --optional shaders",
+        "modsmith update atm9 --file Downloads/atm9-1.2.zip",
+    ),
+)(reported(update_command))
+app.command(
+    "import",
+    epilog=examples(
+        'modsmith import "My Fabric world"', "modsmith import old-pack --dry-run"
+    ),
+)(reported(import_command))
+app.command(
+    "move",
+    epilog=examples(
+        "modsmith move survival creative", "modsmith move survival D:/Games/survival"
+    ),
+)(reported(move_command))
+app.command("delete", epilog=examples("modsmith delete survival"))(
+    reported(delete_command)
+)
+app.add_typer(config_app, name="config")
+
+
+def tolerate_unencodable(*streams: TextIO) -> None:
+    """Write characters an output cannot encode as ``?`` instead of failing.
+
+    Piped or redirected output uses the system code page, so that the shell
+    reading it decodes it correctly. On Windows that code page often cannot
+    hold the emoji found in project names and summaries.
+    """
+    for stream in streams:
+        if isinstance(stream, io.TextIOWrapper):
+            stream.reconfigure(errors="replace")
+
+
+def main() -> None:
+    """Run the command line."""
+    tolerate_unencodable(sys.stdout, sys.stderr)
+    app()

modsmith_cli/commands/__init__.py

@@ -0,0 +1 @@
+"""The commands, one module per group; `modsmith_cli.app` puts them together."""

modsmith_cli/commands/config.py

@@ -0,0 +1,81 @@
+"""``modsmith config``: show and change settings."""
+
+from typing import Annotated
+
+import typer
+from rich.table import Table
+
+from ..context import get
+from ..core import config as settings
+from ..errors import reported
+
+config_app = typer.Typer(
+    help="Show and change settings. With no command, show them all.",
+    invoke_without_command=True,
+)
+
+Key = Annotated[str, typer.Argument(help="The setting's name.", show_default=False)]
+
+
+@config_app.callback()
+@reported
+def show_all(ctx: typer.Context) -> None:
+    """Show every setting, its value and where the value comes from."""
+    if ctx.invoked_subcommand is not None:
+        return
+    app = get(ctx)
+    values = app.config.__dict__
+    origins = settings.sources(app.paths, app.environ)
+    table = Table(box=None, pad_edge=False)
+    table.add_column("Setting", no_wrap=True)
+    # Paths fold rather than shorten, so they can always be copied whole.
+    table.add_column("Value", overflow="fold")
+    table.add_column("From", overflow="fold")
+    for key in settings.SETTINGS:
+        origin = "command line" if key in app.overrides else origins[key]
+        table.add_row(key, settings.shown(key, values[key]), origin)
+    app.out.print(table)
+
+
+@config_app.command("get")
+@reported
+def get_value(ctx: typer.Context, key: Key) -> None:
+    """Print one setting's value."""
+    app = get(ctx)
+    settings.setting(key)
+    app.out.print(settings.shown(key, app.config.__dict__[key]), highlight=False)
+
+
+@config_app.command("set")
+@reported
+def set_value(
+    ctx: typer.Context,
+    key: Key,
+    value: Annotated[str, typer.Argument(help="The new value.", show_default=False)],
+) -> None:
+    """Save a setting to the configuration file."""
+    app = get(ctx)
+    settings.save_setting(app.paths, key, value)
+    app.out.print(f"Saved {key}.")
+    variable = settings.SETTINGS[key].variable
+    if variable and app.environ.get(variable):
+        app.err.print(
+            f"${variable} is set, so it still takes precedence.", style="yellow"
+        )
+
+
+@config_app.command("unset")
+@reported
+def unset_value(ctx: typer.Context, key: Key) -> None:
+    """Remove a setting from the configuration file, so its default applies."""
+    app = get(ctx)
+    settings.save_setting(app.paths, key, None)
+    app.out.print(f"Removed {key}.")
+
+
+@config_app.command("path")
+@reported
+def show_path(ctx: typer.Context) -> None:
+    """Print where the configuration file is."""
+    app = get(ctx)
+    app.out.print(str(app.paths.config_file), highlight=False, soft_wrap=True)

modsmith_cli/commands/contents.py

@@ -0,0 +1,332 @@
+"""Commands that look at and change what an instance holds."""
+
+from collections.abc import Sequence
+from enum import StrEnum
+from typing import Annotated
+
+import typer
+from modsmith import metadata
+from modsmith.errors import DependencyError, InstanceError, ModsmithError
+from modsmith.instances import Changes, Instance, Plan
+from modsmith.platforms import ProjectType
+from rich.table import Table
+from rich.text import Text
+
+from ..context import AppContext, get
+from ..core.config import PLATFORMS
+from ..core.contents import find_contents
+from ..core.errors import AppError
+from ..core.platforms import explained
+from ..core.refs import parse_project
+from ..core.registry import resolve_instance, split_target
+from ..errors import report
+from ..target import DryRun, InstanceName, Yes
+from ..ui import cancellable, confirm, progress, show_plan
+from .install import From, Overwrite, loader_label
+
+SOURCES = {"pack": "pack", "addition": "added", "user": "yours"}
+
+
+class AddedKind(StrEnum):
+    """The kinds of projects that can be added to an instance."""
+
+    MOD = "mod"
+    RESOURCEPACK = "resourcepack"
+    SHADER = "shader"
+
+
+ADDED_KINDS: dict[AddedKind, ProjectType] = {
+    AddedKind.MOD: "mod",
+    AddedKind.RESOURCEPACK: "resourcepack",
+    AddedKind.SHADER: "shader",
+}
+
+Items = Annotated[
+    list[str],
+    typer.Argument(
+        help="The instance, then what to act on. Leave the instance out if you "
+        "have only one.",
+        show_default=False,
+    ),
+]
+
+
+def _heading(name: str, instance: Instance) -> str:
+    state = instance.state
+    if state is None:
+        return name
+    loader = loader_label(state.loader_kind, state.loader_version)
+    pack = f", from {state.pack_name} {state.pack_version}" if state.pack_name else ""
+    return f"{name}: Minecraft {state.minecraft} with {loader}{pack}"
+
+
+def show_command(ctx: typer.Context, name: InstanceName = None) -> None:
+    """List the mods, resource packs and shaders in an instance."""
+    app = get(ctx)
+    instance, _ = resolve_instance(name, app.config, app.paths)
+    app.out.print(Text(_heading(instance.path.name, instance), style="bold"))
+    contents = instance.contents()
+    if not contents:
+        app.out.print("It holds no mods, resource packs or shaders yet.")
+        return
+    table = Table(box=None, pad_edge=False)
+    for column in ("Name", "Version", "From", "State"):
+        table.add_column(column, no_wrap=column != "Name")
+    table.add_column("File", overflow="fold")
+    for item in contents:
+        try:
+            info = metadata.read(instance.path / item.location)
+        except OSError:
+            info = None
+        label = (item.addition.name if item.addition else None) or (
+            info.name if info else item.path.rsplit("/", 1)[-1]
+        )
+        flags = [] if item.enabled else ["off"]
+        if item.addition and item.addition.pinned:
+            flags.append("pinned")
+        table.add_row(
+            label,
+            (info.version if info else None) or "",
+            SOURCES[item.source],
+            ", ".join(flags),
+            item.location,
+        )
+    app.out.print(table)
+
+
+def _notes(instance: Instance, plan: Plan) -> list[Text]:
+    """Say what a plan leaves out, and why it adds what nobody asked for."""
+    state = instance.state
+    held = {item.path for item in state.additions} if state else set[str]()
+    changing = {*plan.changes.added, *plan.changes.updated}
+    notes = [
+        Text(f"  = {item.name} is already in the pack", style="dim")
+        for item in plan.skipped
+    ]
+    for item in plan.additions:
+        if item.path in changing and not item.requested:
+            notes.append(
+                Text(f"    {item.name} comes too, because a mod needs it", style="dim")
+            )
+        elif item.requested and item.path not in changing and item.path in held:
+            notes.append(Text(f"  = {item.name} is already added", style="dim"))
+    notes += [
+        Text(f"  ? {name} has no release for this instance", style="yellow")
+        for name in plan.unavailable
+    ]
+    return notes
+
+
+def add_command(
+    ctx: typer.Context,
+    items: Items,
+    kind: Annotated[
+        AddedKind, typer.Option("--type", "-t", help="The kind of project.")
+    ] = AddedKind.MOD,
+    optional: Annotated[
+        bool, typer.Option("--optional", help="Also add optional dependencies.")
+    ] = 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:
+    """Add mods, resource packs or shaders to an instance, with what they need."""
+    app = get(ctx)
+    instance, _, names = split_target(items, app.config, app.paths)
+    if not names:
+        raise AppError("Name at least one project to add.")
+    refs = [parse_project(name, app.config.default_platform) for name in names]
+    release_only = not (pre or app.config.allow_prereleases)
+    plans: list[tuple[str, Plan]] = []
+    for platform_name in PLATFORMS:
+        wanted = [ref.name for ref in refs if ref.platform == platform_name]
+        if not wanted:
+            continue
+        with (
+            explained(platform_name, wanted),
+            app.platform(platform_name) as platform,
+        ):
+            plan = instance.plan(
+                platform,
+                wanted,
+                project_type=ADDED_KINDS[kind],
+                include_optional=optional,
+                release_only=release_only,
+            )
+        plans.append((platform_name, plan))
+
+    title = f"Add to {instance.path.name}"
+    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}
+    for _, plan in plans:
+        if not plan.ok:
+            raise DependencyError(plan)
+    notes = [note for _, plan in plans for note in _notes(instance, plan)]
+    pending = show_plan(app, changes, sizes, title=title, notes=notes)
+    if not pending or dry_run:
+        return
+    confirm(app, "Add them?", yes=yes)
+    with cancellable() as token, progress(app) as update:
+        for _, plan in plans:
+            instance.add(
+                plan,
+                overwrite=overwrite,
+                adopt_from=from_folders or (),
+                progress=update,
+                cancel=token,
+            )
+    app.out.print(f"Added to {instance.path.name}.")
+
+
+def remove_command(
+    ctx: typer.Context,
+    items: Items,
+    keep_dependencies: Annotated[
+        bool,
+        typer.Option(
+            "--keep-deps", help="Keep dependencies even if nothing needs them."
+        ),
+    ] = False,
+    yes: Yes = False,
+    dry_run: DryRun = False,
+) -> None:
+    """Remove projects you added, and the dependencies nothing else needs."""
+    app = get(ctx)
+    instance, _, names = split_target(items, app.config, app.paths)
+    if not names:
+        raise AppError("Name at least one project to remove.")
+    try:
+        preview = instance.remove(
+            *names, keep_dependencies=keep_dependencies, dry_run=True
+        )
+    except InstanceError as e:
+        raise AppError(
+            str(e) + ".",
+            hint="Files from the pack cannot be removed, but you can turn them off "
+            "with: modsmith disable",
+        ) from e
+    show_plan(app, preview, title=f"Remove from {instance.path.name}")
+    if dry_run:
+        return
+    confirm(app, "Remove them?", yes=yes)
+    instance.remove(*names, keep_dependencies=keep_dependencies)
+    app.out.print(f"Removed from {instance.path.name}.")
+
+
+def _toggle(ctx: typer.Context, items: list[str], *, enabled: bool) -> None:
+    app = get(ctx)
+    instance, _, names = split_target(items, app.config, app.paths)
+    if not names:
+        raise AppError("Name at least one file or project.")
+    targets = find_contents(instance, names)
+    paths = [item.path for item in targets]
+    if enabled:
+        instance.enable(*paths)
+    else:
+        instance.disable(*paths)
+    verb = "Turned on" if enabled else "Turned off"
+    for path in paths:
+        app.out.print(f"{verb} {path}.")
+
+
+def enable_command(ctx: typer.Context, items: Items) -> None:
+    """Turn mods, resource packs or shaders back on."""
+    _toggle(ctx, items, enabled=True)
+
+
+def disable_command(ctx: typer.Context, items: Items) -> None:
+    """Turn mods, resource packs or shaders off, without removing them."""
+    _toggle(ctx, items, enabled=False)
+
+
+def _pin(ctx: typer.Context, items: list[str], *, pinned: bool) -> None:
+    app = get(ctx)
+    instance, _, names = split_target(items, app.config, app.paths)
+    if not names:
+        raise AppError("Name at least one project.")
+    for name in names:
+        try:
+            addition = instance.pin(name, pinned)
+        except ModsmithError as e:
+            raise AppError(
+                f"{name!r} was not added on its own, so it cannot be pinned.",
+                hint="Pack files follow the pack's own updates.",
+            ) from e
+        state = "stays at its release" if pinned else "follows updates again"
+        app.out.print(f"{addition.name} {state}.")
+
+
+def pin_command(ctx: typer.Context, items: Items) -> None:
+    """Keep projects you added at their current release."""
+    _pin(ctx, items, pinned=True)
+
+
+def unpin_command(ctx: typer.Context, items: Items) -> None:
+    """Let pinned projects update again."""
+    _pin(ctx, items, pinned=False)
+
+
+class AdoptFrom(StrEnum):
+    """Which platforms may recognise files."""
+
+    MODRINTH = "modrinth"
+    CURSEFORGE = "curseforge"
+    ALL = "all"
+
+
+def adopt_files(app: AppContext, instance: Instance, names: Sequence[str]) -> int:
+    """Ask each platform to recognise the player's files, and say what it found.
+
+    With several platforms, one that cannot be used is skipped with a note.
+
+    Returns:
+        How many files were recognised.
+    """
+    found = 0
+    for platform_name in names:
+        try:
+            with (
+                cancellable() as token,
+                progress(app) as update,
+                explained(platform_name),
+                app.platform(platform_name) as platform,
+            ):
+                adopted = instance.adopt(platform, progress=update, cancel=token)
+        except AppError as e:
+            if len(names) == 1:
+                raise
+            report(e, app.err, prefix=f"Skipped {platform_name}: ")
+            continue
+        for item in adopted:
+            app.out.print(f"  {item.name}: {item.path}")
+        found += len(adopted)
+    if found:
+        files = "1 file" if found == 1 else f"{found} files"
+        app.out.print(f"{files} can now be updated and removed like added ones.")
+    else:
+        app.out.print("No unrecognised files were found on these platforms.")
+    return found
+
+
+def adopt_command(
+    ctx: typer.Context,
+    name: InstanceName = None,
+    where: Annotated[
+        AdoptFrom,
+        typer.Option("--platform", "-p", help="Which platforms may recognise files."),
+    ] = AdoptFrom.ALL,
+) -> None:
+    """Recognise files you put in an instance, so they can be updated and removed."""
+    app = get(ctx)
+    instance, _ = resolve_instance(name, app.config, app.paths)
+    names = list(PLATFORMS) if where == AdoptFrom.ALL else [where.value]
+    adopt_files(app, instance, names)