map-packer 0.1.0__py3-none-any.whl

cli.py

@@ -0,0 +1,94 @@
+"""map-packer 命令行入口
+
+集中注册各个子命令，提供 Minecraft 地图打包相关的命令行工具
+"""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as package_version
+
+import typer
+
+from commands.init import init as init_command
+from commands.pack import pack as pack_command
+from commands.sync import sync as sync_command
+from lib import ui
+
+
+def _patch_typer_console() -> None:
+    """让 typer 自带的帮助与错误输出也保留颜色
+
+    typer 会自行创建 console，在 ConPTY 终端（Trae、VS Code）中它会重新把
+    终端判定为「legacy Windows」，从而静默去掉 ``--help`` 的所有颜色
+    复用我们强制 ANSI 的设置，让整个 CLI 的观感保持一致
+    """
+    try:
+        from typer import rich_utils
+    except ImportError:  # pragma: no cover - typer 始终带有 rich_utils
+        return
+
+    original = rich_utils._get_rich_console
+
+    def _get_rich_console(stderr: bool = False):
+        console = original(stderr=stderr)
+        console.legacy_windows = False
+        return console
+
+    rich_utils._get_rich_console = _get_rich_console
+
+
+_patch_typer_console()
+
+
+def _version_callback(value: bool) -> None:
+    """处理 --version：打印版本号并退出"""
+    if not value:
+        return
+    try:
+        current = package_version("map-packer")
+    except PackageNotFoundError:
+        current = "0.1.0"
+    ui.console.print(f"[brand]mmp[/brand] [muted]v{current}[/muted]")
+    raise typer.Exit()
+
+
+# 全局 CLI 应用，no_args_is_help 让用户直接运行时可看到帮助信息
+app = typer.Typer(
+    name="mmp",
+    help="A Minecraft Map Packer CLI Tool",
+    epilog="Run [brand]mmp <command> --help[/brand] for details on a command.",
+    no_args_is_help=True,
+    add_completion=False,
+    rich_markup_mode="rich",
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+
+# 注册子命令：mmp init
+app.command(name="init", help="Initialize the current directory as an mmp repository")(
+    init_command
+)
+
+# 注册子命令：mmp sync
+app.command(name="sync", help="Sync a world save into the target directory")(sync_command)
+
+# 注册子命令：mmp pack
+app.command(name="pack", help="Pack the map directory into a compressed archive")(
+    pack_command
+)
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        "-V",
+        help="Show the version and exit",
+        callback=_version_callback,
+        is_eager=True,
+    ),
+) -> None:
+    """Minecraft 地图打包命令行工具"""
+
+
+if __name__ == "__main__":
+    app()

commands/init.py

@@ -0,0 +1,122 @@
+"""初始化命令
+
+把当前目录初始化为一个 mmp 仓库：尝试执行 git init、写入默认的
+mmp.json 配置，并创建地图输出目录
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+from pathlib import Path
+
+import typer
+from rich.markup import escape
+
+from lib import ui
+
+# 默认配置，字段与 sync / pack 命令读取的 data 字段保持一致
+DEFAULT_CONFIG = {
+    "version": "0.0.1",
+    "data": {
+        "sync": {
+            "optimize": True,
+            "prune": True,
+            "output_path": "./map",
+            "exclude": [
+                "session.lock",
+                "level.dat_old",
+            ],
+        },
+        "pack": {
+            "input_path": "./map",
+            "output_path": "./dist",
+            "name": "map",
+            "format": "zip",
+            "compression_level": 6,
+            "minify_datapack": True,
+        },
+    },
+}
+
+# 初始化时写入 .gitignore 的内容
+GITIGNORE_CONTENT = ".env\ndist\n"
+
+
+def _run_git_init(cwd: Path) -> bool:
+    """尝试在当前目录执行 git init，成功返回 True
+
+    git 不可用或执行失败时返回 False，由调用方决定如何提示
+    """
+    if shutil.which("git") is None:
+        return False
+    try:
+        result = subprocess.run(
+            ["git", "init"],
+            cwd=cwd,
+            capture_output=True,
+            text=True,
+        )
+    except OSError:
+        return False
+    return result.returncode == 0
+
+
+def init() -> None:
+    """Initialize the current directory as an mmp repository.
+
+    Rules:
+    - run `git init` in the current directory when git is available;
+    - write the default mmp.json when it does not exist yet;
+    - create the output directory from data.sync.output_path.
+
+    Raises:
+        typer.Exit: When mmp.json already exists.
+    """
+    cwd = Path.cwd()
+    config_path = cwd / "mmp.json"
+
+    ui.header("init", "Initialize the current directory as an mmp repository")
+
+    if config_path.exists():
+        ui.error(
+            f"[path]{escape(str(config_path))}[/path] already exists",
+            hint="remove it first to re-initialize",
+        )
+        raise typer.Exit(code=1)
+
+    # 尝试执行 git init，git 不可用时仅提示，不阻断初始化
+    if _run_git_init(cwd):
+        ui.phase("Git", "[ok]initialized[/ok] [muted]repository[/muted]")
+    else:
+        ui.phase("Git", "[muted]skipped · git not available[/muted]")
+
+    # 写入 .gitignore（追加模式，若已有该文件则保留原有内容）
+    gitignore_path = cwd / ".gitignore"
+    needs_gitignore = False
+    if gitignore_path.exists():
+        content = gitignore_path.read_text(encoding="utf-8")
+        if ".env" not in content.splitlines():
+            gitignore_path.write_text(content + GITIGNORE_CONTENT, encoding="utf-8")
+            needs_gitignore = True
+    else:
+        gitignore_path.write_text(GITIGNORE_CONTENT, encoding="utf-8")
+        needs_gitignore = True
+    if needs_gitignore:
+        ui.phase("Gitignore", f"[path].gitignore[/path]")
+
+    # 写入默认配置
+    with open(config_path, "w", encoding="utf-8") as f:
+        json.dump(DEFAULT_CONFIG, f, indent=4)
+        f.write("\n")
+    ui.phase("Config", f"[path]{escape(str(config_path))}[/path]")
+
+    # 创建地图输出目录
+    output_path = Path(DEFAULT_CONFIG["data"]["sync"]["output_path"])
+    target = (cwd / output_path).resolve()
+    target.mkdir(parents=True, exist_ok=True)
+    ui.phase("Map", f"[path]{escape(str(target))}[/path]")
+
+    ui.blank()
+    ui.success("[bold]Initialized mmp repository[/bold]")

commands/pack.py

@@ -0,0 +1,281 @@
+"""地图打包命令
+
+将同步后的地图目录打包为压缩文件，打包格式、压缩等级与输出位置
+通过 mmp.json 的 data.pack 字段配置
+"""
+
+from __future__ import annotations
+
+import tarfile
+import time
+import zipfile
+from pathlib import Path
+
+import typer
+from rich.markup import escape
+from rich.progress import (
+    BarColumn,
+    MofNCompleteColumn,
+    Progress,
+    ProgressColumn,
+    SpinnerColumn,
+    TextColumn,
+    TimeElapsedColumn,
+)
+
+from lib import ui
+from lib.config import SUPPORTED_VERSION, get_config
+from lib.datapack import minify_datapacks
+
+# 各配置项的默认值，字段与 init 写入的 data.pack 保持一致
+DEFAULT_INPUT = "./map"
+DEFAULT_OUTPUT = "./dist"
+DEFAULT_NAME = "map"
+DEFAULT_FORMAT = "zip"
+DEFAULT_COMPRESSION_LEVEL = 6
+DEFAULT_MINIFY_DATAPACK = True
+
+# 支持的打包格式及其输出扩展名
+FORMATS: dict[str, str] = {
+    "zip": ".zip",
+    "tar": ".tar",
+    "tar.gz": ".tar.gz",
+    "tar.bz2": ".tar.bz2",
+    "tar.xz": ".tar.xz",
+}
+
+# 常见别名统一归一化为标准格式名
+FORMAT_ALIASES: dict[str, str] = {
+    "tgz": "tar.gz",
+    "tbz": "tar.bz2",
+    "tbz2": "tar.bz2",
+    "txz": "tar.xz",
+}
+
+
+def _normalize_format(raw: str) -> str:
+    """把用户填写的格式归一化为标准格式名，未知格式原样返回"""
+    fmt = raw.strip().lower()
+    return FORMAT_ALIASES.get(fmt, fmt)
+
+
+def _level_range(fmt: str) -> tuple[int, int] | None:
+    """返回指定格式支持的压缩等级范围，tar 不支持压缩时返回 None"""
+    if fmt == "tar":
+        return None
+    if fmt == "tar.bz2":
+        return (1, 9)
+    return (0, 9)
+
+
+def _collect_files(root: Path) -> list[tuple[Path, str]]:
+    """收集目录下所有文件，返回 (绝对路径, 归档内相对路径) 列表"""
+    files: list[tuple[Path, str]] = []
+    for path in sorted(root.rglob("*")):
+        if path.is_file():
+            files.append((path, path.relative_to(root).as_posix()))
+    return files
+
+
+def _write_zip(target: Path, files: list[tuple[Path, str]], level: int, advance) -> None:
+    """把文件写入 zip 归档，level 为 0 时改用仅存储模式"""
+    if level == 0:
+        with zipfile.ZipFile(target, "w", compression=zipfile.ZIP_STORED) as zf:
+            for full, rel in files:
+                zf.write(full, arcname=rel)
+                advance()
+        return
+
+    with zipfile.ZipFile(
+        target, "w", compression=zipfile.ZIP_DEFLATED, compresslevel=level
+    ) as zf:
+        for full, rel in files:
+            zf.write(full, arcname=rel)
+            advance()
+
+
+def _write_tar(target: Path, fmt: str, files: list[tuple[Path, str]], level: int, advance) -> None:
+    """把文件写入 tar 归档，按格式选择对应的压缩器与参数"""
+    mode = {
+        "tar": "w",
+        "tar.gz": "w:gz",
+        "tar.bz2": "w:bz2",
+        "tar.xz": "w:xz",
+    }[fmt]
+
+    kwargs: dict[str, int] = {}
+    if fmt in ("tar.gz", "tar.bz2"):
+        kwargs["compresslevel"] = level
+    elif fmt == "tar.xz":
+        kwargs["preset"] = level
+
+    with tarfile.open(target, mode, **kwargs) as tf:
+        for full, rel in files:
+            tf.add(full, arcname=rel)
+            advance()
+
+
+def pack(
+    config: str = typer.Option(
+        "./mmp.json",
+        "--config",
+        "-c",
+        help="Path to the mmp.json configuration file",
+    ),
+) -> None:
+    """Pack the target directory into a compressed archive.
+
+    Rules:
+    - the source directory, output directory, archive name, format and
+      compression level come from the "data.pack" field in mmp.json;
+    - when "data.pack.minify_datapack" is enabled, datapack text files have their
+      comments (lines starting with #) and blank lines removed, and every JSON
+      file is rewritten without indentation or spaces before packing;
+    - the packed size change and shrink percentage are reported when packing;
+    - supported formats are zip, tar, tar.gz, tar.bz2 and tar.xz;
+    - mmp.json must declare version 0.0.1, the only supported format version.
+
+    Args:
+        config: Path to the mmp.json configuration file.
+
+    Raises:
+        typer.Exit: When the source directory is missing, the format is
+            unsupported, or the mmp.json version is unsupported.
+    """
+    # 读取配置：打包选项位于 mmp.json 的 data.pack 字段
+    config_data = get_config(config)
+    version = config_data.get("version")
+    if version != SUPPORTED_VERSION:
+        ui.error(
+            f"Unsupported mmp.json version: [path]{escape(str(version))}[/path]",
+            hint=f"only version {SUPPORTED_VERSION} is supported",
+        )
+        raise typer.Exit(code=1)
+
+    data = config_data.get("data") or {}
+    pack_config = data.get("pack") or {}
+
+    source = (
+        Path(pack_config.get("input_path", DEFAULT_INPUT)).expanduser().resolve()
+    )
+    output_dir = (
+        Path(pack_config.get("output_path", DEFAULT_OUTPUT)).expanduser().resolve()
+    )
+    name = str(pack_config.get("name", DEFAULT_NAME))
+    fmt = _normalize_format(str(pack_config.get("format", DEFAULT_FORMAT)))
+    try:
+        level = int(pack_config.get("compression_level", DEFAULT_COMPRESSION_LEVEL))
+    except (TypeError, ValueError):
+        ui.error(
+            "Invalid [path]data.pack.compression_level[/path] in mmp.json",
+            hint="expected an integer",
+        )
+        raise typer.Exit(code=1)
+    minify = bool(pack_config.get("minify_datapack", DEFAULT_MINIFY_DATAPACK))
+
+    # 校验源目录
+    if not source.is_dir():
+        ui.error(
+            f"Input directory not found: [path]{escape(str(source))}[/path]",
+            hint="run mmp sync first or point data.pack.input_path at a map directory",
+        )
+        raise typer.Exit(code=1)
+
+    # 校验打包格式
+    if fmt not in FORMATS:
+        supported = ", ".join(FORMATS)
+        ui.error(
+            f"Unsupported pack format: [path]{escape(fmt)}[/path]",
+            hint=f"supported formats: {supported}",
+        )
+        raise typer.Exit(code=1)
+
+    # 校验压缩等级
+    bounds = _level_range(fmt)
+    if bounds is not None and not bounds[0] <= level <= bounds[1]:
+        ui.error(
+            f"Invalid compression_level [num]{level}[/num] for format [path]{escape(fmt)}[/path]",
+            hint=f"expected an integer between {bounds[0]} and {bounds[1]}",
+        )
+        raise typer.Exit(code=1)
+
+    target = output_dir / f"{name}{FORMATS[fmt]}"
+
+    ui.header("pack", "Pack the map directory into a compressed archive")
+    ui.panel(
+        "Configuration",
+        [
+            ("Source", f"[path]{escape(str(source))}[/path]"),
+            ("Output", f"[path]{escape(str(target))}[/path]"),
+            ("Format", f"[value]{escape(fmt)}[/value]"),
+            ("Level", f"[num]{level}[/num]" if bounds else "[muted]n/a[/muted]"),
+            ("Minify", "[ok]enabled[/ok]" if minify else "[muted]disabled[/muted]"),
+        ],
+    )
+    ui.blank()
+
+    with ui.console.status("[brand]Scanning files…[/brand]", spinner="dots"):
+        files = _collect_files(source)
+    ui.phase("Scanning", f"[num]{len(files):,}[/num] [muted]files[/muted]")
+
+    if not files:
+        ui.error(
+            f"No files found in [path]{escape(str(source))}[/path]",
+            hint="run mmp sync first to populate the map directory",
+        )
+        raise typer.Exit(code=1)
+
+    # 记录精简前的源目录总体积，用于展示打包带来的体积变化
+    source_size = sum(path.stat().st_size for path, _rel in files)
+
+    # 精简数据包：去除注释与空行、把 JSON 压缩为无缩进无空格格式
+    if minify:
+        ui.blank()
+        with ui.console.status("[brand]Minifying datapacks…[/brand]", spinner="dots"):
+            datapack_files, datapack_saved = minify_datapacks(source)
+        if datapack_files:
+            ui.phase(
+                "Minify",
+                f"[num]{datapack_files:,}[/num] [muted]file(s) · saved[/muted] "
+                f"[num]{ui.format_size(datapack_saved)}[/num]",
+            )
+        else:
+            ui.phase("Minify", "[muted]nothing to minify[/muted]")
+
+    output_dir.mkdir(parents=True, exist_ok=True)
+    started = time.perf_counter()
+
+    columns: list[ProgressColumn] = [
+        SpinnerColumn(style="brand"),
+        TextColumn("{task.description}"),
+        BarColumn(
+            bar_width=None,
+            complete_style="brand",
+            finished_style="ok",
+            pulse_style="brand",
+        ),
+        MofNCompleteColumn(),
+        TimeElapsedColumn(),
+    ]
+
+    with Progress(*columns, console=ui.console) as progress:
+        task = progress.add_task(ui.task_label("Packing"), total=len(files))
+
+        def advance() -> None:
+            progress.advance(task)
+
+        if fmt == "zip":
+            _write_zip(target, files, level, advance)
+        else:
+            _write_tar(target, fmt, files, level, advance)
+
+    elapsed = time.perf_counter() - started
+    size = target.stat().st_size
+
+    ui.blank()
+    ui.success(
+        f"[bold]Pack complete[/bold] [muted]in {elapsed:.2f}s[/muted]  "
+        f"[muted]·[/muted]  [num]{len(files):,}[/num] [muted]files →[/muted] "
+        f"[path]{escape(str(target))}[/path] [muted]({ui.format_size(size)})[/muted]"
+    )
+    ui.phase("Size", ui.size_delta(source_size, size))