modsmith-cli 0.1.1__py3-none-any.whl

modsmith_cli/core/registry.py

@@ -0,0 +1,183 @@
+"""Find the player's instances by name or by path.
+
+An instance is a folder under the instances folder, named after the instance,
+or a folder elsewhere that the app was told about.
+"""
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+from modsmith.errors import InstanceError
+from modsmith.instances import Instance, InstanceState
+
+from .config import Config
+from .errors import AppError
+from .paths import AppPaths
+
+
+@dataclass(frozen=True)
+class Entry:
+    """One instance the app knows.
+
+    Attributes:
+        name: Its folder's name.
+        path: Its folder.
+        state: What it holds, or None if that could not be read.
+        external: Whether it is outside the instances folder.
+        problem: Why its state could not be read, or None.
+    """
+
+    name: str
+    path: Path
+    state: InstanceState | None
+    external: bool = False
+    problem: str | None = None
+
+
+def _looks_like_path(text: str) -> bool:
+    return any(mark in text for mark in ("/", "\\")) or text.startswith((".", "~"))
+
+
+def locate(text: str, config: Config) -> Path:
+    """Return the folder that a name or a path refers to. It may not exist yet.
+
+    A name is looked up in the instances folder. Anything with a slash, or
+    starting with ``.`` or ``~``, is a path.
+    """
+    if _looks_like_path(text) or Path(text).is_absolute():
+        return Path(text).expanduser().resolve()
+    return config.instances_dir / text
+
+
+def _state(instance: Instance) -> InstanceState | None:
+    """Read an instance's state, reporting corruption as an `AppError`."""
+    try:
+        return instance.state
+    except InstanceError as e:
+        raise AppError(str(e)) from e
+
+
+def open_instance(
+    text: str, config: Config, paths: AppPaths | None = None
+) -> tuple[Instance, InstanceState]:
+    """Open an existing instance by name or path.
+
+    A name is looked up in the instances folder, then among the instances kept
+    elsewhere.
+
+    Raises:
+        AppError: There is no instance there, or its state is corrupt.
+    """
+    instance = Instance(locate(text, config))
+    state = _state(instance)
+    if state is None and paths is not None and not _looks_like_path(text):
+        for path in external_paths(paths):
+            if path.name == text:
+                instance = Instance(path)
+                state = _state(instance)
+                break
+    if state is None:
+        raise AppError(
+            f"There is no instance called {text!r}.",
+            hint="Run modsmith list to see your instances.",
+        )
+    return instance, state
+
+
+def resolve_instance(
+    text: str | None, config: Config, paths: AppPaths
+) -> tuple[Instance, InstanceState]:
+    """Open the instance a command names, or the only one if it names none.
+
+    Raises:
+        AppError: There is no such instance, there are none, or there are
+            several and none was named.
+    """
+    if text is not None:
+        return open_instance(text, config, paths)
+    usable = [
+        entry for entry in list_instances(config, paths) if entry.state is not None
+    ]
+    if len(usable) == 1:
+        return open_instance(str(usable[0].path), config, paths)
+    if not usable:
+        raise AppError(
+            "There are no instances yet.",
+            hint="Install a pack with modsmith install, or start one with modsmith create.",
+        )
+    names = ", ".join(entry.name for entry in usable)
+    raise AppError("Name the instance to use.", hint=f"Your instances: {names}.")
+
+
+def split_target(
+    words: list[str], config: Config, paths: AppPaths
+) -> tuple[Instance, InstanceState, list[str]]:
+    """Separate an instance name from the items a command acts on.
+
+    The first word names the instance if one has that name. Otherwise, when
+    there is only one instance, every word is an item.
+
+    Raises:
+        AppError: No instance is named and there is not exactly one.
+    """
+    if words:
+        try:
+            instance, state = open_instance(words[0], config, paths)
+        except AppError:
+            pass
+        else:
+            return instance, state, words[1:]
+    instance, state = resolve_instance(None, config, paths)
+    return instance, state, words
+
+
+def external_paths(paths: AppPaths) -> list[Path]:
+    """Return the instances kept outside the instances folder."""
+    try:
+        data = json.loads(paths.external_file.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        return []
+    except ValueError as e:
+        raise AppError(f"{paths.external_file} is corrupt: {e}") from e
+    return [Path(item) for item in data if isinstance(item, str)]
+
+
+def remember_external(paths: AppPaths, path: Path, keep: bool = True) -> None:
+    """Add an instance outside the instances folder to the list, or remove it."""
+    known = [item for item in external_paths(paths) if item != path]
+    if keep:
+        known.append(path)
+    paths.external_file.parent.mkdir(parents=True, exist_ok=True)
+    text = json.dumps([str(item) for item in known], indent=2)
+    paths.external_file.write_text(text, encoding="utf-8")
+
+
+def _entry(path: Path, external: bool) -> Entry | None:
+    """Describe a folder, or return None if it is not an instance."""
+    try:
+        state = Instance(path).state
+    except InstanceError as e:
+        return Entry(path.name, path, None, external, str(e))
+    if state is None:
+        return None
+    return Entry(path.name, path, state, external)
+
+
+def list_instances(config: Config, paths: AppPaths) -> list[Entry]:
+    """List every instance the app knows, sorted by name.
+
+    Folders in the instances folder that are not instances are skipped, and so
+    are remembered folders that are no longer instances.
+    """
+    found: list[Entry] = []
+    if config.instances_dir.is_dir():
+        for path in sorted(config.instances_dir.iterdir()):
+            entry = _entry(path, external=False) if path.is_dir() else None
+            if entry is not None:
+                found.append(entry)
+    for path in external_paths(paths):
+        entry = _entry(path, external=True)
+        if entry is not None:
+            found.append(entry)
+    return sorted(found, key=lambda item: item.name.lower())

modsmith_cli/errors.py

@@ -0,0 +1,180 @@
+"""Turn errors into short messages with a hint, instead of tracebacks."""
+
+import functools
+from collections.abc import Callable
+from dataclasses import dataclass, field
+
+import typer
+from modsmith.errors import (
+    Cancelled,
+    DependencyError,
+    DownloadError,
+    LockedError,
+    ModsmithError,
+    NetworkError,
+    UnresolvedEntriesError,
+)
+from modsmith.platforms import Release
+from rich.console import Console
+from rich.text import Text
+
+from .core.errors import AppError
+
+BUSY = 429
+# The exit status of a command stopped with Ctrl+C, as shells expect.
+INTERRUPTED = 130
+
+
+@dataclass(frozen=True)
+class Report:
+    """What to tell the player about an error.
+
+    Attributes:
+        message: What went wrong.
+        hint: What to do about it, or None.
+        details: One line per item that failed, such as each file.
+    """
+
+    message: str
+    hint: str | None = None
+    details: list[str] = field(default_factory=list[str])
+
+
+def _network_hint(error: NetworkError) -> str | None:
+    """Say what to do about a failed request, going by its status."""
+    if error.status is None:
+        return "Check your internet connection, then try again."
+    if error.status == BUSY or error.status >= 500:
+        return "The service is busy or having trouble. Try again later."
+    return None
+
+
+def _unresolved(error: UnresolvedEntriesError) -> Report:
+    details: list[str] = []
+    for entry in error.entries:
+        name = entry.path or (
+            entry.ref and f"{entry.ref.platform} file {entry.ref.file_id}"
+        )
+        page = f"  download it from {entry.manual_url}" if entry.manual_url else ""
+        details.append(f"{name}{page}")
+    return Report(
+        (
+            "1 file cannot"
+            if len(error.entries) == 1
+            else f"{len(error.entries)} files cannot"
+        )
+        + " be downloaded automatically.",
+        "Download them by hand into one folder, then run the command again "
+        "with --from <folder>.",
+        details,
+    )
+
+
+def _dependencies(error: DependencyError) -> Report:
+    plan = error.plan
+    resolution = plan.resolution
+    names = {item.project_id: item.name for item in plan.additions}
+
+    def named(release: Release) -> str:
+        name = names.get(release.project_id)
+        return f"{name} {release.version}" if name and release.version else release.name
+
+    details = [
+        f"{named(item.release)} cannot be used with {named(item.chosen)}"
+        for item in resolution.conflicts
+    ]
+    details += [
+        f"{named(item.release)} needs "
+        + (
+            item.project.name
+            if item.project
+            else str(item.dependency.project_id or item.dependency.release_id)
+        )
+        + ", which has no release for this instance"
+        for item in resolution.missing
+        if item.dependency.kind == "required"
+    ]
+    return Report("This cannot be installed, because of these problems.", None, details)
+
+
+def describe(error: AppError | ModsmithError) -> Report:
+    """Describe an app or library error for the player."""
+    if isinstance(error, AppError):
+        return Report(error.message, error.hint)
+    if isinstance(error, Cancelled):
+        return Report(
+            "Cancelled.",
+            "Nothing was changed. Run the command again to carry on where it stopped.",
+        )
+    if isinstance(error, LockedError):
+        return Report(
+            str(error),
+            "Another Modsmith is changing these files. Try again when it is done.",
+        )
+    if isinstance(error, DownloadError):
+        return Report(
+            str(error),
+            "Nothing was changed. Run the command again to retry.",
+            list(error.failures),
+        )
+    if isinstance(error, UnresolvedEntriesError):
+        return _unresolved(error)
+    if isinstance(error, DependencyError):
+        return _dependencies(error)
+    if isinstance(error, NetworkError):
+        return Report(str(error), _network_hint(error))
+    return Report(str(error))
+
+
+def report(
+    error: AppError | ModsmithError, console: Console | None = None, prefix: str = ""
+) -> None:
+    """Print an error's message, details and hint to standard error.
+
+    Args:
+        error: The error.
+        console: Where to print. Defaults to standard error.
+        prefix: Shown instead of ``Error:``, for errors that did not stop the
+            command.
+    """
+    found = describe(error)
+    out = console or Console(stderr=True, highlight=False)
+    label = (prefix, "yellow") if prefix else ("Error: ", "bold red")
+    out.print(Text.assemble(label, found.message), soft_wrap=True)
+    for line in found.details:
+        out.print(Text(f"  {line}"), soft_wrap=True)
+    if found.hint:
+        # Hints often hold a command, which must stay on one line to be copied.
+        out.print(Text(found.hint, style="dim"), soft_wrap=True)
+
+
+def _console(kwargs: dict[str, object]) -> Console | None:
+    """Find the run's error console through the command's context, if it has one."""
+    ctx = kwargs.get("ctx")
+    if isinstance(ctx, typer.Context):
+        root = ctx.find_root().obj
+        return getattr(root, "err", None)
+    return None
+
+
+def reported[**P, R](command: Callable[P, R]) -> Callable[P, R]:
+    """Wrap a command so known errors are reported and end the command.
+
+    Cancelled commands and Ctrl+C exit with 130, other errors with 1.
+    """
+
+    @functools.wraps(command)
+    def run(*args: P.args, **kwargs: P.kwargs) -> R:
+        try:
+            return command(*args, **kwargs)
+        except Cancelled as e:
+            report(e, _console(kwargs))
+            raise typer.Exit(INTERRUPTED) from e
+        except KeyboardInterrupt as e:
+            report(Cancelled(), _console(kwargs))
+            raise typer.Exit(INTERRUPTED) from e
+        except (AppError, ModsmithError) as e:
+            report(e, _console(kwargs))
+            raise typer.Exit(1) from e
+
+    return run

modsmith_cli/target.py

@@ -0,0 +1,43 @@
+"""Shared arguments and help for commands that act on an instance."""
+
+from typing import Annotated
+
+import typer
+
+from .core.config import load_config
+from .core.errors import AppError
+from .core.paths import AppPaths
+from .core.registry import list_instances
+
+# Click rewraps help text, except a paragraph whose first line is this mark.
+KEEP_LINES = "\b"
+
+
+def complete_instances(incomplete: str) -> list[str]:
+    """Offer instance names for shell completion."""
+    try:
+        paths = AppPaths.from_environment()
+        entries = list_instances(load_config(paths), paths)
+    except AppError:
+        return []
+    return [entry.name for entry in entries if entry.name.startswith(incomplete)]
+
+
+def examples(*lines: str) -> str:
+    """Format example commands for the end of a command's help."""
+    listed = "\n".join(f"  {line}" for line in lines)
+    return f"Examples:\n\n{KEEP_LINES}\n{listed}"
+
+
+InstanceName = Annotated[
+    str | None,
+    typer.Argument(
+        help="The instance. Can be left out when you have only one.",
+        autocompletion=complete_instances,
+        show_default=False,
+    ),
+]
+Yes = Annotated[bool, typer.Option("--yes", "-y", help="Do it without asking.")]
+DryRun = Annotated[
+    bool, typer.Option("--dry-run", help="Show what would change, and change nothing.")
+]

modsmith_cli/ui.py

@@ -0,0 +1,219 @@
+"""How commands talk to the player: plans, confirmation, progress and Ctrl+C."""
+
+import signal
+from collections.abc import Generator, Mapping, Sequence
+from contextlib import contextmanager
+from dataclasses import dataclass
+from types import FrameType
+
+import typer
+from modsmith.instances import Changes
+from modsmith.progress import CancelToken, Progress, ProgressCallback
+from rich.progress import (
+    BarColumn,
+    TaskID,
+    TaskProgressColumn,
+    TextColumn,
+    TimeRemainingColumn,
+)
+from rich.progress import Progress as Bars
+from rich.text import Text
+
+from .context import AppContext
+from .core.errors import AppError
+
+# How many paths of each kind a plan lists before summing up the rest.
+SHOWN_PER_KIND = 12
+TASK_NAMES = {
+    "files": "Downloading files",
+    "overrides": "Writing pack files",
+    "minecraft": "Downloading Minecraft",
+    "libraries": "Downloading libraries",
+    "java": "Downloading Java",
+    "identify": "Reading files",
+    "fetch": "Downloading",
+    "download": "Downloading",
+    "processors": "Running installer steps",
+}
+
+
+@dataclass(frozen=True)
+class PlanRow:
+    """One kind of change in a plan, as shown to the player."""
+
+    symbol: str
+    style: str
+    label: str
+    paths: tuple[str, ...]
+
+
+def _size(total: int) -> str:
+    """Format a byte count, such as 12.3 MB."""
+    size = float(total)
+    for unit in ("B", "KB", "MB", "GB"):
+        if size < 1000 or unit == "GB":
+            return f"{size:.0f} {unit}" if unit == "B" else f"{size:.1f} {unit}"
+        size /= 1000
+    return f"{size:.1f} GB"
+
+
+def show_plan(
+    app: AppContext,
+    changes: Changes,
+    sizes: Mapping[str, int | None] | None = None,
+    *,
+    title: str | None = None,
+    notes: Sequence[Text] = (),
+) -> bool:
+    """Print what a change would do. Returns False if it would change nothing.
+
+    Args:
+        app: The run.
+        changes: The changes, from a library diff or plan.
+        sizes: The download size of each path, where known.
+        title: A heading for the plan.
+        notes: Lines to print after the changes and before the summary.
+    """
+    rows = [
+        PlanRow("+", "green", "add", changes.added),
+        PlanRow("~", "cyan", "update", changes.updated),
+        PlanRow("-", "red", "remove", changes.removed),
+        PlanRow("!", "yellow", "keep your version of", changes.conflicts),
+        PlanRow("!", "yellow", "keep, though no longer needed,", changes.orphaned),
+    ]
+    if title:
+        app.out.print(Text(title, style="bold"))
+    for row in rows:
+        listed = row.paths if app.verbose else row.paths[:SHOWN_PER_KIND]
+        for path in listed:
+            app.out.print(Text.assemble((f"  {row.symbol} ", row.style), path))
+        hidden = len(row.paths) - len(listed)
+        if hidden:
+            app.out.print(Text(f"  {row.symbol} and {hidden} more", style=row.style))
+    for path in changes.superseded:
+        app.out.print(Text.assemble(("  = ", "dim"), f"{path} is now part of the pack"))
+    for note in notes:
+        app.out.print(note)
+    counts = [f"{len(row.paths)} to {row.label}" for row in rows[:3] if row.paths]
+    kept = len(changes.conflicts) + len(changes.orphaned)
+    if kept:
+        counts.append(f"{kept} of your changes kept")
+    if not counts:
+        app.out.print("Nothing to change.")
+        return False
+    pending = [*changes.added, *changes.updated]
+    total = sum((sizes or {}).get(path) or 0 for path in pending)
+    summary = ", ".join(counts)
+    if total:
+        summary += f"; {_size(total)} to download"
+    app.out.print(Text(summary + ".", style="bold"))
+    return True
+
+
+def confirm(app: AppContext, question: str, *, yes: bool) -> None:
+    """Ask before changing files, unless ``--yes`` was given.
+
+    Raises:
+        AppError: There is no terminal to ask in, so ``--yes`` is needed.
+        typer.Exit: The player said no.
+    """
+    if yes:
+        return
+    if not app.services.interactive():
+        raise AppError(
+            "This command changes files and there is no terminal to confirm in.",
+            hint="Run it again with --yes.",
+        )
+    if not typer.confirm(question, default=True):
+        app.err.print("Nothing was changed.")
+        raise typer.Exit(0)
+
+
+def confirm_name(app: AppContext, name: str, *, yes: bool, force: bool) -> None:
+    """Ask the player to type a name before something that cannot be undone.
+
+    Raises:
+        AppError: ``--yes`` was given without ``--force``, or there is no
+            terminal.
+        typer.Exit: The player typed something else.
+    """
+    if yes:
+        if not force:
+            raise AppError(
+                "This cannot be undone, so --yes alone is not enough.",
+                hint="Add --force as well.",
+            )
+        return
+    if not app.services.interactive():
+        raise AppError(
+            "This command cannot be undone and there is no terminal to confirm in.",
+            hint="Run it again with --yes --force.",
+        )
+    typed = typer.prompt(f"Type {name} to confirm", default="", show_default=False)
+    if typed != name:
+        app.err.print("Nothing was changed.")
+        raise typer.Exit(0)
+
+
+@contextmanager
+def progress(app: AppContext) -> Generator[ProgressCallback]:
+    """Show the library's progress updates as bars, when standard error is a terminal."""
+    if not app.err.is_terminal:
+        yield lambda update: None
+        return
+    columns = (
+        TextColumn("{task.description}"),
+        BarColumn(),
+        TaskProgressColumn(),
+        TimeRemainingColumn(),
+    )
+    with Bars(*columns, console=app.err, transient=True) as bars:
+        tasks: dict[tuple[str, str], TaskID] = {}
+
+        def update(item: Progress) -> None:
+            key = (item.task, item.unit)
+            if key not in tasks:
+                label = TASK_NAMES.get(item.task, item.task.capitalize())
+                tasks[key] = bars.add_task(label, total=item.total)
+            bars.update(tasks[key], completed=item.current, total=item.total)
+
+        yield update
+
+
+@contextmanager
+def cancellable() -> Generator[CancelToken]:
+    """Turn the first Ctrl+C into a clean stop, through a `CancelToken`.
+
+    The library then stops at a safe point and raises `Cancelled`. A second
+    Ctrl+C stops at once.
+    """
+    token = CancelToken()
+    previous = signal.getsignal(signal.SIGINT)
+
+    def stop(signum: int, frame: FrameType | None) -> None:
+        if token.cancelled:
+            raise KeyboardInterrupt
+        token.cancel()
+
+    try:
+        signal.signal(signal.SIGINT, stop)
+    except ValueError:
+        # Signal handlers can only be set from the main thread.
+        yield token
+        return
+    try:
+        yield token
+    finally:
+        signal.signal(signal.SIGINT, previous)
+
+
+def show_changelog(app: AppContext, title: str, text: str, *, lines: int) -> None:
+    """Print a changelog under a heading, cut to its first lines unless verbose."""
+    kept = [line.rstrip() for line in text.strip().splitlines()]
+    if not kept:
+        return
+    app.out.print(Text(title, style="bold"))
+    shown = kept if app.verbose else kept[:lines]
+    app.out.print(Text("\n".join(shown)))
+    if len(shown) < len(kept):
+        app.out.print(Text("... (-v shows all of it)", style="dim"))