map-packer 0.1.0__tar.gz

map_packer-0.1.0/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2026 yed
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

map_packer-0.1.0/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: map-packer
+Version: 0.1.0
+Summary: A Minecraft Map Packer CLI Tool
+License-Expression: MIT
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: nbtlib>=2.0.4
+Requires-Dist: python-dotenv>=1.2.4
+Requires-Dist: rich>=15.0.0
+Requires-Dist: typer>=0.27.2
+Dynamic: license-file
+
+# A Minecraft Map Packer CLI Tool

map_packer-0.1.0/README.md

@@ -0,0 +1 @@
+# A Minecraft Map Packer CLI Tool

map_packer-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "map-packer"
+version = "0.1.0"
+description = "A Minecraft Map Packer CLI Tool"
+readme = "README.md"
+requires-python = ">=3.14"
+license = "MIT"
+license-files = ["LICENSE"]
+
+dependencies = [
+    "nbtlib>=2.0.4",
+    "python-dotenv>=1.2.4",
+    "rich>=15.0.0",
+    "typer>=0.27.2",
+]
+
+[project.scripts]
+mmp = "cli:app"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+py-modules = ["cli"]
+
+[tool.setuptools.packages.find]
+where = ["src"]

map_packer-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

map_packer-0.1.0/src/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()

map_packer-0.1.0/src/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]")

map_packer-0.1.0/src/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))