PyREUser3 0.1.0__py3-none-any.whl

pyreuser3/__init__.py

@@ -0,0 +1,65 @@
+"""RE User3 JSON 工具包的公开导出入口。
+
+较重的转换模块会依赖 Rich 等命令行显示库。这里使用惰性导出，
+让 `pyreuser3-web --help` 和 `python -m pyreuser3.web --help` 这类轻量入口
+不需要提前加载完整导出器或封包器。
+"""
+
+from __future__ import annotations
+
+from importlib import import_module
+from typing import Any
+
+__all__ = [
+    "BinaryReader",
+    "ClassDef",
+    "FieldDef",
+    "PackError",
+    "ParseError",
+    "TypeDB",
+    "REUser3Converter",
+    "RSZ_MAGIC",
+    "User3Exporter",
+    "User3Packer",
+    "USR_MAGIC",
+]
+
+_EXPORT_MODULES = {
+    "BinaryReader": ".core",
+    "ParseError": ".core",
+    "RSZ_MAGIC": ".core",
+    "USR_MAGIC": ".core",
+    "ClassDef": ".schema",
+    "FieldDef": ".schema",
+    "TypeDB": ".schema",
+    "PackError": ".pack",
+    "User3Packer": ".pack",
+    "User3Exporter": ".export",
+    "REUser3Converter": ".api",
+}
+
+
+def __getattr__(name: str) -> Any:
+    """首次访问公开名称时再惰性导入对应模块。
+
+    PEP 562 的模块级 ``__getattr__`` 钩子：仅当访问 ``__all__`` 中声明的名称
+    且该名称尚未缓存到模块全局时才会触发，从而实现按需导入的惰性导出。
+
+    参数：
+        name (str): 正在访问的属性名（通常是 ``__all__`` 中的某个公开名称）。
+
+    返回：
+        Any: 解析并缓存后的目标对象（类、函数或常量）。
+
+    异常：
+        AttributeError: 当 ``name`` 不在惰性导出表 ``_EXPORT_MODULES`` 中时抛出。
+    """
+    module_name = _EXPORT_MODULES.get(name)
+    if module_name is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+    # 导入后把结果缓存到 globals，后续访问不再触发 __getattr__。
+    module = import_module(module_name, __name__)
+    value = getattr(module, name)
+    globals()[name] = value
+    return value

pyreuser3/__main__.py

@@ -0,0 +1,7 @@
+"""Run the PyREUser3 CLI with ``python -m pyreuser3``."""
+
+from __future__ import annotations
+
+from .cli import main
+
+raise SystemExit(main())

pyreuser3/api.py

@@ -0,0 +1,410 @@
+"""对外使用的高层 API。
+
+`REUser3Converter` 是推荐给其他项目调用的门面类。它把底层的
+`User3Exporter` 和 `User3Packer` 包装成更稳定的工作流：
+解析、导出、封包，以及“解析后交给 callback 修改再自动封包”。
+"""
+
+from __future__ import annotations
+
+import inspect
+import json
+import re
+from pathlib import Path
+from typing import Any, Callable, Optional
+
+from .core import RSZ_MAGIC, USR_MAGIC
+from .export import User3Exporter
+from .pack import User3Packer
+
+# 导出/封包过程中流转的 JSON 树，结构随文件而异，故用 Any 表示。
+JsonTree = Any
+# 用户提供的修补回调：接收 (data) 或 (data, source_path)，可返回新树或就地修改后返回 None。
+PatchCallback = Callable[..., Optional[JsonTree]]
+
+
+class REUser3Converter:
+    """RE Engine `.user.3` 与 JSON 互转的可复用门面类。
+
+    封装解析、导出、封包以及“解析→回调修改→封包”的完整工作流，并统一处理
+    模板路径、il2cpp dump、magic 等配置，让外部调用方无需直接接触底层
+    导出器/封包器。
+    """
+
+    def __init__(
+        self,
+        schema_path: str | Path | None = None,
+        il2cpp_dump_path: str | Path | None = None,
+        tree_depth: int | str = "auto",
+        schema_dir: str | Path | None = None,
+        user_magic: int = USR_MAGIC,
+        rsz_magic: int = RSZ_MAGIC,
+    ) -> None:
+        """初始化转换器。
+
+        参数：
+            schema_path (str | Path | None): 必填，RE_RSZ 模板 JSON 文件路径。
+            il2cpp_dump_path (str | Path | None): ``il2cpp_dump.json`` 路径；解析和导出时必填，
+                封包时可选但建议传入，用于枚举名反查。
+            tree_depth (int | str): 对象引用树展开深度，支持非负整数或 ``"auto"``。
+            schema_dir (str | Path | None): 旧参数名兼容入口，实际含义仍是模板 JSON 文件。
+            user_magic (int): ``.user.3`` 文件头 magic，默认沿用当前项目值。
+            rsz_magic (int): RSZ 数据块 magic，默认沿用当前项目值。
+
+        返回：
+            None: 构造函数，仅初始化实例属性。
+
+        异常：
+            TypeError: 当 ``schema_path`` 和 ``schema_dir`` 都缺失时抛出。
+        """
+        # 兼容旧调用方的 `schema_dir=` 写法，但内部统一使用 schema_path。
+        if schema_path is None:
+            schema_path = schema_dir
+        if schema_path is None:
+            raise TypeError("schema_path is required")
+        self.schema_path = Path(schema_path)
+        self.il2cpp_dump_path = Path(il2cpp_dump_path) if il2cpp_dump_path else None
+        self.tree_depth = tree_depth
+        self.user_magic = int(user_magic)
+        self.rsz_magic = int(rsz_magic)
+
+    def export_directory(
+        self,
+        user3_root: str | Path,
+        output_root: str | Path,
+        exclude_regexes: list[str] | None = None,
+    ) -> dict[str, int]:
+        """批量导出目录或单文件下的 `.user.3`。
+
+        参数：
+            user3_root (str | Path): ``.user.3`` 根目录或单个 ``.user.3`` 文件。
+            output_root (str | Path): JSON 输出根目录。
+            exclude_regexes (list[str] | None): 用于排除相对路径的正则表达式列表。
+
+        返回：
+            dict[str, int]: 统计字典，含 ``total``、``success``、``failed`` 三个计数。
+        """
+        exporter = self._new_exporter(user3_root, output_root, exclude_regexes)
+        return exporter.run()
+
+    def export_file(
+        self,
+        user3_path: str | Path,
+        json_path: str | Path,
+    ) -> Path:
+        """导出单个 `.user.3` 文件到指定 JSON 路径。
+
+        参数：
+            user3_path (str | Path): 源 ``.user.3`` 文件。
+            json_path (str | Path): 目标 JSON 文件。
+
+        返回：
+            Path: 实际写入的 JSON 文件路径。
+        """
+        # 单文件导出复用 parse_file，确保 API 直接解析和批量导出的
+        # JSON 形状一致，减少后续封包时的分支差异。
+        tree = self.parse_file(user3_path, round_floats=True)
+        target = Path(json_path)
+        target.parent.mkdir(parents=True, exist_ok=True)
+
+        with target.open("w", encoding="utf-8") as f:
+            json.dump(tree, f, ensure_ascii=False, indent=2)
+        return target
+
+    def parse_file(self, user3_path: str | Path, round_floats: bool = True) -> JsonTree:
+        """把单个 `.user.3` 解析成导出器使用的紧凑 JSON 树。
+
+        参数：
+            user3_path (str | Path): 源 ``.user.3`` 文件。
+            round_floats (bool): 是否把浮点数四舍五入到 4 位，方便人工阅读。
+
+        返回：
+            JsonTree: 可直接修改或传给 :meth:`pack` 的紧凑 JSON 树。
+        """
+        exporter = self._new_exporter(user3_path, Path.cwd(), [])
+        # 单文件解析不写 Enums_Internal.json，但仍需要从 il2cpp_dump.json
+        # 构建枚举表和枚举上下文，否则固定枚举值无法转换成可读标签。
+        self._prepare_exporter_metadata(exporter)
+        tree = exporter._parse_user3(Path(user3_path))
+        tree = exporter._postprocess_enum_nodes(tree)
+        tree = exporter._finalize_export_tree(tree)
+        if round_floats:
+            return exporter._round_export_floats(tree)
+        return tree
+
+    def parse_pack_file(self, user3_path: str | Path) -> JsonTree:
+        """把单个 `.user.3` 解析成适合修改后稳定封包的实例表 JSON。
+
+        普通导出和 :meth:`parse_file` 仍然返回 readable JSON；只有需要封回
+        ``.user.3`` 的流程才应使用这个完整实例表结构。
+
+        参数：
+            user3_path (str | Path): 源 ``.user.3`` 文件。
+
+        返回：
+            JsonTree: 含完整实例表（``_instances`` 等键）的封包格式 JSON。
+        """
+        exporter = self._new_exporter(user3_path, Path.cwd(), [])
+        self._prepare_exporter_metadata(exporter)
+        return exporter._parse_user3_pack(Path(user3_path))
+
+    def pack_directory(
+        self,
+        json_root: str | Path,
+        output_root: str | Path,
+        exclude_regexes: list[str] | None = None,
+    ) -> dict[str, int]:
+        """批量将 JSON 文件封回 `.user.3`。
+
+        参数：
+            json_root (str | Path): JSON 文件或 JSON 根目录。
+            output_root (str | Path): ``.user.3`` 输出根目录。
+            exclude_regexes (list[str] | None): 用于排除 JSON 相对路径的正则表达式列表。
+
+        返回：
+            dict[str, int]: 统计字典，含 ``total``、``success``、``failed`` 三个计数。
+        """
+        packer = self._new_packer(output_root)
+        return packer.pack_directory(json_root, output_root, exclude_regexes)
+
+    def pack_file(self, json_path: str | Path, user3_path: str | Path) -> Path:
+        """把单个 JSON 文件封包到指定 `.user.3` 路径。
+
+        参数：
+            json_path (str | Path): 源 JSON 文件。
+            user3_path (str | Path): 输出 ``.user.3`` 文件路径。
+
+        返回：
+            Path: 实际写入的 ``.user.3`` 文件路径。
+        """
+        packer = self._new_packer(Path(user3_path).parent)
+        return packer.pack_json_file(json_path, user3_path)
+
+    def pack(self, data: Any) -> bytes:
+        """把内存中的 JSON 树直接编码为 `.user.3` 二进制。
+
+        参数：
+            data (Any): readable JSON 对象/数组，或 :meth:`parse_pack_file` 返回的实例表 JSON。
+
+        返回：
+            bytes: 可直接写入文件的 ``.user.3`` 字节串。
+        """
+        return self._new_packer(None).pack(data)
+
+    def patch_file(
+        self,
+        user3_path: str | Path,
+        output_path: str | Path,
+        callback: PatchCallback,
+    ) -> Path:
+        """解析、交给 callback 修改、封包并写出单个 `.user.3`。
+
+        callback 可以接收 ``(data)`` 或 ``(data, source_path)``。这里的 ``data``
+        是完整实例表 JSON。callback 既可以返回一个新的 JSON 树，也可以
+        原地修改 ``data`` 后返回 ``None``。
+
+        参数：
+            user3_path (str | Path): 源 ``.user.3`` 文件。
+            output_path (str | Path): 修改后 ``.user.3`` 的写入路径。
+            callback (PatchCallback): 用户提供的 JSON 修改函数。
+
+        返回：
+            Path: 实际写入的 ``.user.3`` 文件路径。
+        """
+        source = Path(user3_path)
+        # 修改并封回时使用完整实例表格式，避免 readable 树里的旧引用编号
+        # 在重建实例表时变成悬空引用。
+        data = self.parse_pack_file(source)
+        modified = self._run_callback(callback, data, source)
+        if modified is None:
+            modified = data
+        target = Path(output_path)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_bytes(self.pack(modified))
+        return target
+
+    def patch_directory(
+        self,
+        user3_root: str | Path,
+        output_root: str | Path,
+        callback: PatchCallback,
+        include_regexes: list[str] | None = None,
+        exclude_regexes: list[str] | None = None,
+    ) -> dict[str, int]:
+        """批量查找匹配的 `.user.3`，用 callback 修改后自动封包。
+
+        ``include_regexes`` 和 ``exclude_regexes`` 都匹配相对 ``user3_root`` 的
+        路径，并统一使用 ``/`` 作为路径分隔符，避免 Windows 与类 Unix
+        路径差异影响正则。
+
+        参数：
+            user3_root (str | Path): ``.user.3`` 根目录或单个文件。
+            output_root (str | Path): 修改后文件的输出根目录。
+            callback (PatchCallback): 用户提供的 JSON 修改函数。
+            include_regexes (list[str] | None): 只处理匹配这些正则的相对路径。
+            exclude_regexes (list[str] | None): 跳过匹配这些正则的相对路径。
+
+        返回：
+            dict[str, int]: 统计字典，含 ``total``、``success``、``failed``、``skipped`` 四个计数。
+        """
+        source_root = Path(user3_root)
+        target_root = Path(output_root)
+        files = self._discover_user3_files(source_root)
+        include_patterns = [re.compile(p) for p in (include_regexes or [])]
+        exclude_patterns = [re.compile(p) for p in (exclude_regexes or [])]
+
+        total = success = failed = skipped = 0
+        for file_path in files:
+            # 单文件模式使用文件名；目录模式使用相对路径，以便输出时还原目录。
+            rel = (
+                file_path.name
+                if source_root.is_file()
+                else file_path.relative_to(source_root).as_posix()
+            )
+            if include_patterns and not any(
+                pattern.search(rel) for pattern in include_patterns
+            ):
+                skipped += 1
+                continue
+            if any(pattern.search(rel) for pattern in exclude_patterns):
+                skipped += 1
+                continue
+
+            total += 1
+            output_path = target_root / (
+                file_path.name
+                if source_root.is_file()
+                else file_path.relative_to(source_root)
+            )
+            try:
+                # 每个文件独立处理，单个文件失败不会影响整个目录批处理。
+                self.patch_file(file_path, output_path, callback)
+                success += 1
+            except Exception:
+                failed += 1
+        return {
+            "total": total,
+            "success": success,
+            "failed": failed,
+            "skipped": skipped,
+        }
+
+    def _new_exporter(
+        self,
+        user3_root: str | Path,
+        output_root: str | Path,
+        exclude_regexes: list[str] | None,
+    ) -> User3Exporter:
+        """按当前配置创建导出器实例。
+
+        参数：
+            user3_root (str | Path): ``.user.3`` 输入根目录或单个文件。
+            output_root (str | Path): JSON 输出根目录。
+            exclude_regexes (list[str] | None): 排除相对路径的正则表达式列表。
+
+        返回：
+            User3Exporter: 已用当前模板、dump、magic 等配置初始化的导出器。
+
+        异常：
+            FileNotFoundError: 当导出所需的 ``il2cpp_dump_path`` 未配置时抛出。
+        """
+        if self.il2cpp_dump_path is None:
+            raise FileNotFoundError("il2cpp_dump_path is required for exporting JSON")
+        return User3Exporter(
+            user3_root=user3_root,
+            schema_dir=self.schema_path,
+            output_root=output_root,
+            tree_depth=self.tree_depth,
+            exclude_regexes=exclude_regexes or [],
+            il2cpp_dump_path=self.il2cpp_dump_path,
+            user_magic=self.user_magic,
+            rsz_magic=self.rsz_magic,
+        )
+
+    def _new_packer(self, output_root: str | Path | None) -> User3Packer:
+        """按当前配置创建封包器实例。
+
+        参数：
+            output_root (str | Path | None): 默认输出根目录，可为 ``None``。
+
+        返回：
+            User3Packer: 已用当前模板、dump、magic 等配置初始化的封包器。
+        """
+        return User3Packer(
+            schema_dir=self.schema_path,
+            il2cpp_dump_path=self.il2cpp_dump_path,
+            output_root=output_root,
+            user_magic=self.user_magic,
+            rsz_magic=self.rsz_magic,
+        )
+
+    def _prepare_exporter_metadata(self, exporter: User3Exporter) -> None:
+        """为单文件解析准备枚举表和枚举上下文。
+
+        参数：
+            exporter (User3Exporter): 待填充枚举索引的导出器实例。
+
+        返回：
+            None: 直接在 ``exporter`` 上设置枚举查找表与上下文。
+
+        异常：
+            FileNotFoundError: 当 ``il2cpp_dump_path`` 缺失或不是文件时抛出。
+        """
+        if self.il2cpp_dump_path is None or not self.il2cpp_dump_path.is_file():
+            raise FileNotFoundError("il2cpp_dump_path is required for parsing JSON")
+        with self.il2cpp_dump_path.open("r", encoding="utf-8") as f:
+            il2cpp_dump = json.load(f)
+        # 导出器批处理时会写出 Enums_Internal.json；这里是内存解析，
+        # 因此只构建运行时索引，不产生额外文件。
+        enums_internal = exporter.export_enums_internal(il2cpp_dump)
+        exporter.enum_lookup = exporter._build_enum_lookup_from_enums_internal(
+            enums_internal
+        )
+        enum_context = exporter.export_enum_context_internal(il2cpp_dump)
+        exporter._apply_enum_context(enum_context)
+        exporter._ensure_enum_lookup()
+
+    @staticmethod
+    def _discover_user3_files(user3_root: Path) -> list[Path]:
+        """发现单文件或目录下的 `.user.3` 文件。
+
+        参数：
+            user3_root (Path): ``.user.3`` 根目录或单个文件路径。
+
+        返回：
+            list[Path]: 排序后的 ``.user.3`` 文件路径列表（单文件时只含一项）。
+
+        异常：
+            FileNotFoundError: 当路径不存在或目录下没有 ``.user.3`` 时抛出。
+        """
+        if user3_root.is_file():
+            return [user3_root]
+        if not user3_root.is_dir():
+            raise FileNotFoundError(f"user3 root not found: {user3_root}")
+        files = sorted(user3_root.rglob("*.user.3"))
+        if not files:
+            raise FileNotFoundError(f"no *.user.3 found under: {user3_root}")
+        return files
+
+    @staticmethod
+    def _run_callback(
+        callback: PatchCallback, data: JsonTree, source_path: Path
+    ) -> JsonTree | None:
+        """根据 callback 参数个数自动决定是否传入源路径。
+
+        参数：
+            callback (PatchCallback): 用户提供的修改函数。
+            data (JsonTree): 待修改的完整实例表 JSON。
+            source_path (Path): 源 ``.user.3`` 文件路径。
+
+        返回：
+            JsonTree | None: callback 返回的新树，或 ``None``（表示就地修改）。
+        """
+        try:
+            param_count = len(inspect.signature(callback).parameters)
+        except (TypeError, ValueError):
+            # 某些可调用对象可能无法通过 inspect 取得签名，默认按完整参数调用。
+            param_count = 2
+        if param_count <= 1:
+            return callback(data)
+        return callback(data, source_path)

pyreuser3/cli.py

@@ -0,0 +1,207 @@
+"""Command line interface for the PyREUser3 package."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from importlib.metadata import PackageNotFoundError, version
+from typing import Sequence
+
+from .core import RSZ_MAGIC, USR_MAGIC
+from .export import User3Exporter
+from .pack import User3Packer
+from .rich_ui import get_console
+
+
+def parse_int_arg(value: str) -> int:
+    """Parse decimal or 0x-prefixed integer command line values."""
+    return int(value, 0)
+
+
+def package_version() -> str:
+    """Return installed package version, with a source-tree fallback."""
+    try:
+        return version("PyREUser3")
+    except PackageNotFoundError:
+        return "0.1.0"
+
+
+def normalize_tree_depth(value: str) -> int | str:
+    """Normalize tree depth argument to an integer or the string 'auto'."""
+    text = value.strip().lower()
+    if text == "auto":
+        return "auto"
+    depth = int(text)
+    if depth < 0:
+        raise argparse.ArgumentTypeError("tree depth must be non-negative or 'auto'")
+    return depth
+
+
+def add_magic_args(parser: argparse.ArgumentParser) -> None:
+    """Add common .user.3 and RSZ magic options to a subparser."""
+    parser.add_argument(
+        "--user-magic",
+        type=parse_int_arg,
+        default=USR_MAGIC,
+        help=f"USR file magic as decimal or hex (default: 0x{USR_MAGIC:08x}).",
+    )
+    parser.add_argument(
+        "--rsz-magic",
+        type=parse_int_arg,
+        default=RSZ_MAGIC,
+        help=f"RSZ block magic as decimal or hex (default: 0x{RSZ_MAGIC:08x}).",
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the top-level CLI parser."""
+    parser = argparse.ArgumentParser(
+        prog="pyreuser3",
+        description="Convert RE Engine .user.3 files to JSON and pack them back.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {package_version()}",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    export_parser = subparsers.add_parser(
+        "export",
+        help="Export .user.3 files to JSON.",
+    )
+    export_parser.add_argument(
+        "--input-dir",
+        "-i",
+        required=True,
+        help="Root directory or single .user.3 file to export.",
+    )
+    export_parser.add_argument(
+        "--schema-path",
+        "--schema-dir",
+        "-s",
+        dest="schema_path",
+        required=True,
+        help="Explicit RE_RSZ schema JSON file path.",
+    )
+    export_parser.add_argument(
+        "--output-dir",
+        "-o",
+        required=True,
+        help="Root output directory for exported JSON files.",
+    )
+    export_parser.add_argument(
+        "--tree-depth",
+        "-d",
+        type=normalize_tree_depth,
+        default="auto",
+        help="Tree depth as a non-negative integer or 'auto' (default: auto).",
+    )
+    export_parser.add_argument(
+        "--exclude-regex",
+        "-x",
+        action="append",
+        default=[],
+        help="Regex to exclude matching relative file paths. Can be used multiple times.",
+    )
+    export_parser.add_argument(
+        "--il2cpp-dump-path",
+        "-p",
+        required=True,
+        help="Path to il2cpp_dump.json, used to generate enum labels.",
+    )
+    add_magic_args(export_parser)
+    export_parser.set_defaults(func=run_export)
+
+    pack_parser = subparsers.add_parser(
+        "pack",
+        help="Pack .user.3 JSON files back to .user.3.",
+    )
+    pack_parser.add_argument(
+        "--input-json",
+        "-j",
+        required=True,
+        help="JSON file or root directory that contains .user.3.json files.",
+    )
+    pack_parser.add_argument(
+        "--schema-path",
+        "--schema-dir",
+        "-s",
+        dest="schema_path",
+        required=True,
+        help="Explicit RE_RSZ schema JSON file path.",
+    )
+    pack_parser.add_argument(
+        "--output-dir",
+        "-o",
+        required=True,
+        help="Root output directory for packed .user.3 files.",
+    )
+    pack_parser.add_argument(
+        "--il2cpp-dump-path",
+        "-p",
+        default="",
+        help="Optional il2cpp_dump.json path, used for enum name lookup.",
+    )
+    pack_parser.add_argument(
+        "--exclude-regex",
+        "-x",
+        action="append",
+        default=[],
+        help="Regex to exclude matching relative JSON paths. Can be used multiple times.",
+    )
+    add_magic_args(pack_parser)
+    pack_parser.set_defaults(func=run_pack)
+
+    return parser
+
+
+def run_export(args: argparse.Namespace) -> int:
+    """Run the export subcommand."""
+    console = get_console()
+    console.log("Exporting .user.3 files to JSON...")
+    exporter = User3Exporter(
+        user3_root=args.input_dir,
+        schema_dir=args.schema_path,
+        output_root=args.output_dir,
+        tree_depth=args.tree_depth,
+        exclude_regexes=args.exclude_regex,
+        il2cpp_dump_path=args.il2cpp_dump_path,
+        user_magic=args.user_magic,
+        rsz_magic=args.rsz_magic,
+    )
+    result = exporter.run()
+    console.log("Export complete:", json.dumps(result, ensure_ascii=False))
+    return 1 if result.get("failed", 0) else 0
+
+
+def run_pack(args: argparse.Namespace) -> int:
+    """Run the pack subcommand."""
+    console = get_console()
+    console.log("Packing JSON files to .user.3...")
+    packer = User3Packer(
+        schema_dir=args.schema_path,
+        il2cpp_dump_path=args.il2cpp_dump_path or None,
+        output_root=args.output_dir,
+        user_magic=args.user_magic,
+        rsz_magic=args.rsz_magic,
+    )
+    result = packer.pack_directory(
+        json_root=args.input_json,
+        output_root=args.output_dir,
+        exclude_regexes=args.exclude_regex,
+    )
+    console.log("Pack complete:", json.dumps(result, ensure_ascii=False))
+    return 1 if result.get("failed", 0) else 0
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """CLI entry point used by the pyreuser3 console script."""
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return int(args.func(args))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())