modmgr 0.0.1__py3-none-any.whl

modmgr/__init__.py

@@ -0,0 +1,16 @@
+"""modmanager package."""
+
+__all__ = [
+    "engine",
+    "pathstyle",
+    "paths",
+    "iojson",
+    "database_ops",
+    "schema",
+    "validation",
+    "rule_aggregator",
+    "backup_ops",
+    "forest_visual",
+    "bootstrap",
+    "orchestrator",
+]

modmgr/acf_parser.py

@@ -0,0 +1,302 @@
+"""ACF file format parser for Steam workshop mods.
+
+ACF (Valve Application Configuration Format) is similar to VDF.
+Used for appmanifest_*.acf (game metadata) and appworkshop_*.acf (workshop mods).
+
+Example appmanifest structure:
+    "AppState"
+    {
+        "appid" "270150"
+        "name" "Running with Rifles"
+        "StateFlags" "4"
+        "LastUpdated" "..."
+        ...
+    }
+
+Example appworkshop structure:
+    "WorkshopItemDetails"
+    {
+        "0" { "publishedfileid" "2606099273" ... }
+        "1" { "publishedfileid" "3428584891" ... }
+        ...
+    }
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+import vdf
+
+
+def parse_appmanifest_acf(acf_path: str) -> dict[str, Any]:
+    """
+    Parse appmanifest_*.acf to get game information.
+
+    Args:
+        acf_path: Path to appmanifest_*.acf file
+
+    Returns:
+        {
+          "appid": "270150",
+          "name": "Running with Rifles",
+          "installdir": "Running with Rifles",
+          ...
+        }
+
+    Raises:
+        FileNotFoundError: If file does not exist
+        ValueError: If ACF format is invalid
+    """
+    acf_file = Path(acf_path)
+    if not acf_file.exists():
+        raise FileNotFoundError(f"ACF file not found: {acf_path}")
+
+    try:
+        with open(acf_file, "r", encoding="utf-8") as f:
+            data = vdf.load(f)
+    except Exception as e:
+        raise ValueError(f"Failed to parse ACF file: {e}")
+
+    app_state = data.get("AppState", {})
+    if isinstance(app_state, dict):
+        return dict(app_state)
+    else:
+        return {}
+
+
+def parse_appworkshop_acf(acf_path: str) -> list[dict[str, Any]]:
+    """
+    Parse appworkshop_*.acf to get workshop mod information.
+
+    Args:
+        acf_path: Path to appworkshop_*.acf file (e.g., appworkshop_270150.acf)
+
+    Returns:
+        List of mod metadata:
+        [
+          {
+            "publishedfileid": "2606099273",
+            "installed": True,
+            "workingbuild": "...",
+            ...
+          },
+          ...
+        ]
+
+    Raises:
+        FileNotFoundError: If file does not exist
+        ValueError: If ACF format is invalid
+    """
+    acf_file = Path(acf_path)
+    if not acf_file.exists():
+        raise FileNotFoundError(f"ACF file not found: {acf_path}")
+
+    try:
+        with open(acf_file, "r", encoding="utf-8") as f:
+            data = vdf.load(f)
+    except Exception as e:
+        raise ValueError(f"Failed to parse ACF file: {e}")
+
+    items = []
+    workshop_items = data.get("WorkshopItemDetails", {})
+
+    if isinstance(workshop_items, dict):
+        # Sort by numeric keys
+        sorted_keys = sorted(
+            [k for k in workshop_items.keys() if k.isdigit()],
+            key=int
+        )
+
+        for key in sorted_keys:
+            entry = workshop_items[key]
+            if isinstance(entry, dict):
+                items.append(dict(entry))
+
+    return items
+
+
+def find_appmanifest_acf_files(steamapps_path: str) -> dict[str, str]:
+    """
+    Find all appmanifest_*.acf files in steamapps directory.
+
+    Args:
+        steamapps_path: Path to steamapps/ directory
+
+    Returns:
+        Dict: {appid: path_to_appmanifest_acf}
+        Example: {"270150": "/path/to/appmanifest_270150.acf", ...}
+    """
+    raise NotImplementedError("To be implemented in M1.1")
+
+
+def find_appworkshop_acf_files(steamapps_path: str) -> dict[str, str]:
+    """
+    Find all appworkshop_*.acf files in steamapps directory.
+
+    Args:
+        steamapps_path: Path to steamapps/ directory
+
+    Returns:
+        Dict: {appid: path_to_appworkshop_acf}
+        Example: {"270150": "/path/to/appworkshop_270150.acf", ...}
+    """
+    raise NotImplementedError("To be implemented in M1.1")
+
+
+def get_workshop_timeupdated(steamapps_path: str, appid: str, contentid: str | None = None) -> str:
+    """从 appworkshop_{appid}.acf 读取 timeupdated 字段并返回字符串。
+
+    ACF 文件位于 ``steamapps_path/workshop/`` 子目录下。
+
+    若传入 contentid，则优先在 WorkshopItemsInstalled 和 WorkshopItemDetails
+    中查找指定 contentid 的 timeupdated，找到即返回（不降级到其他策略）。
+
+    若 contentid 为 None，使用原有策略（按优先级）:
+    1. ``AppWorkshop.TimeLastUpdated`` 顶层时间戳
+    2. ``AppWorkshop.WorkshopItemsInstalled.*.timeupdated``
+    3. ``AppWorkshop.WorkshopItemDetails.*.timeupdated`` 取最大值
+
+    若文件不存在或所有字段缺失 → 返回 "0"。
+
+    Returns:
+        timeupdated 的字符串（数字字符串），或 "0"
+    """
+    acf_path = Path(steamapps_path) / "workshop" / f"appworkshop_{appid}.acf"
+    if not acf_path.exists():
+        return "0"
+
+    try:
+        with open(acf_path, "r", encoding="utf-8") as f:
+            data = vdf.load(f)
+    except Exception:
+        return "0"
+
+    if not isinstance(data, dict):
+        return "0"
+
+    # Unwrap the top-level "AppWorkshop" key
+    app_ws = data.get("AppWorkshop")
+    if isinstance(app_ws, dict):
+        ws_data = app_ws
+    else:
+        ws_data = data
+
+    # If a specific contentid is requested, do targeted lookup first
+    if contentid is not None:
+        # WorkshopItemsInstalled -> contentid -> timeupdated
+        try:
+            installed = ws_data.get("WorkshopItemsInstalled")
+            if isinstance(installed, dict):
+                app_entry = installed.get(contentid)
+                if isinstance(app_entry, dict):
+                    tu = app_entry.get("timeupdated")
+                    if tu is not None:
+                        return str(tu)
+        except (ValueError, TypeError):
+            pass
+
+        # WorkshopItemDetails -> contentid -> timeupdated (fallback)
+        try:
+            details = ws_data.get("WorkshopItemDetails")
+            if isinstance(details, dict):
+                entry = details.get(contentid)
+                if isinstance(entry, dict):
+                    tu = entry.get("timeupdated")
+                    if tu is not None:
+                        return str(tu)
+        except (ValueError, TypeError):
+            pass
+
+        return "0"
+
+    # ── contentid is None: use legacy multi-source strategy ──────────────
+    timestamps: list[int] = []
+
+    # 1. WorkshopItemsInstalled -> <appid> -> timeupdated
+    try:
+        installed = ws_data.get("WorkshopItemsInstalled")
+        if isinstance(installed, dict):
+            app_entry = installed.get(appid)
+            if isinstance(app_entry, dict):
+                tu = app_entry.get("timeupdated")
+                if tu is not None:
+                    timestamps.append(int(str(tu)))
+    except (ValueError, TypeError):
+        pass
+
+    # 2. WorkshopItemDetails -> <index> -> timeupdated
+    try:
+        details = ws_data.get("WorkshopItemDetails")
+        if isinstance(details, dict):
+            for _key, entry in details.items():
+                if isinstance(entry, dict):
+                    tu = entry.get("timeupdated")
+                    if tu is not None:
+                        timestamps.append(int(str(tu)))
+    except (ValueError, TypeError):
+        pass
+
+    if timestamps:
+        return str(max(timestamps))
+
+    # 3. Fallback: top-level TimeLastUpdated (e.g. "1778139487")
+    try:
+        tlu = ws_data.get("TimeLastUpdated")
+        if tlu is not None:
+            return str(int(str(tlu)))
+    except (ValueError, TypeError):
+        pass
+
+    return "0"
+
+
+def get_workshop_latest_timeupdated(steamapps_path: str, appid: str, contentid: str) -> str:
+    """从 appworkshop_{appid}.acf 读取特定 contentid 的 latest_timeupdated。
+
+    读取 ``steamapps_path/workshop/appworkshop_{appid}.acf``，
+    解包 AppWorkshop，查 WorkshopItemDetails.{contentid}.latest_timeupdated。
+
+    Returns:
+        latest_timeupdated 的字符串，或 "0"
+    """
+    acf_path = Path(steamapps_path) / "workshop" / f"appworkshop_{appid}.acf"
+    if not acf_path.exists():
+        return "0"
+
+    try:
+        with open(acf_path, "r", encoding="utf-8") as f:
+            data = vdf.load(f)
+    except Exception:
+        return "0"
+
+    if not isinstance(data, dict):
+        return "0"
+
+    app_ws = data.get("AppWorkshop")
+    if not isinstance(app_ws, dict):
+        return "0"
+
+    details = app_ws.get("WorkshopItemDetails")
+    if not isinstance(details, dict):
+        return "0"
+
+    entry = details.get(contentid)
+    if not isinstance(entry, dict):
+        return "0"
+
+    ltu = entry.get("latest_timeupdated")
+    if ltu is None:
+        return "0"
+
+    return str(ltu)
+
+
+__all__ = [
+    "parse_appmanifest_acf",
+    "parse_appworkshop_acf",
+    "find_appmanifest_acf_files",
+    "find_appworkshop_acf_files",
+    "get_workshop_timeupdated",
+    "get_workshop_latest_timeupdated",
+]

modmgr/apply_ops.py

@@ -0,0 +1,145 @@
+"""apply_ops.py — Pure apply primitive.
+
+Executes file-to-file apply operations according to a pre-computed plan.
+Does NOT derive backup_dirs, does NOT handle directories, does NOT make decisions.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+from typing import Any, Callable
+
+# ── Public API ──────────────────────────────────────────────────────────
+
+
+def apply_entries(
+    entries_by_backup_dir: dict[str, list[dict[str, Any]]],
+    *,
+    dry_run: bool = False,
+    on_progress: Callable[..., None] | None = None,
+) -> dict[str, Any]:
+    """Execute file-to-file apply.
+
+    Args:
+        entries_by_backup_dir: {backup_dir_path: [{path, request}, ...]}
+        dry_run: If True, simulate without modifying files.
+        on_progress: Optional progress callback.
+
+    Returns:
+        dict with keys: ok, applied, skipped, errors, warnings, diagnostics, dry_run
+    """
+    applied: list[dict[str, Any]] = []
+    skipped: list[dict[str, Any]] = []
+    errors: list[str] = []
+    warnings: list[str] = []
+    diagnostics: dict[str, Any] = {}
+
+    total = sum(len(v) for v in entries_by_backup_dir.values())
+    finished = 0
+
+    for backup_dir, entries in entries_by_backup_dir.items():
+        _notify(on_progress, "apply", finished, total, f"Applying in {backup_dir}")
+
+        for entry in entries:
+            target_path = entry["path"]
+            request = entry.get("request")
+
+            if request is None:
+                skipped.append({"path": target_path, "reason": "no source (vacuous node)"})
+                finished += 1
+                continue
+
+            action = request["action"]
+            source_path = request["path"]
+
+            # ── File-to-file guard ─────────────────────────────────
+            if not _is_file_path(target_path):
+                errors.append(f"E_APPLY_NOT_FILE: target path is not a file: {target_path}")
+                finished += 1
+                continue
+
+            try:
+                if action == "delete":
+                    if not dry_run:
+                        _assert_is_file(target_path, action)
+                        os.remove(target_path)
+                    applied.append({
+                        "action": "delete",
+                        "target": target_path,
+                        "size": 0,
+                        "mtime": 0,
+                        "is_dir": False,
+                    })
+
+                elif action in ("replace", "create"):
+                    if not source_path or source_path == "!":
+                        errors.append(f"E_APPLY_MISSING_SOURCE: no source for {action} on {target_path}")
+                        finished += 1
+                        continue
+
+                    if not dry_run:
+                        _assert_is_file(source_path, action)
+                        os.makedirs(os.path.dirname(target_path), exist_ok=True)
+                        shutil.copy2(source_path, target_path)
+
+                    st = os.stat(source_path) if os.path.exists(source_path) else None
+                    applied.append({
+                        "action": action,
+                        "source": source_path,
+                        "target": target_path,
+                        "size": st.st_size if st else 0,
+                        "mtime": st.st_mtime if st else 0,
+                        "is_dir": False,
+                    })
+
+                else:
+                    skipped.append({"path": target_path, "action": action, "reason": "unknown action"})
+
+            except FileNotFoundError as exc:
+                errors.append(f"E_APPLY_MISSING_SOURCE: {source_path}: {exc}")
+            except PermissionError as exc:
+                errors.append(f"E_APPLY_PERMISSION: {target_path}: {exc}")
+            except OSError as exc:
+                errors.append(f"E_APPLY_FAILED: {target_path}: {exc}")
+
+            finished += 1
+            _notify(on_progress, "apply", finished, total)
+
+    if not applied and not errors:
+        warnings.append("W_APPLY_NO_EFFECT: no entries were applied")
+
+    return {
+        "ok": len(errors) == 0,
+        "applied": applied,
+        "skipped": skipped,
+        "errors": errors,
+        "warnings": warnings,
+        "diagnostics": diagnostics,
+        "dry_run": dry_run,
+    }
+
+
+# ── Internal helpers ────────────────────────────────────────────────────
+
+
+def _is_file_path(path: str) -> bool:
+    """True if path does NOT end with '/' (file semantics)."""
+    return not path.endswith("/")
+
+
+def _assert_is_file(path: str, action: str) -> None:
+    """Raise if path is a directory (apply is file-to-file only)."""
+    if os.path.isdir(path):
+        raise IsADirectoryError(f"E_APPLY_DIRECTORY_NOT_ALLOWED: {action} target is a directory: {path}")
+
+
+def _notify(
+    on_progress: Callable[..., None] | None,
+    step: str,
+    finished: int,
+    total: int,
+    message: str = "",
+) -> None:
+    if on_progress:
+        on_progress(step, finished, total, message)

modmgr/backup_dir_builder.py

@@ -0,0 +1,218 @@
+"""backup_dir_builder.py — Automatic backup directory path derivation.
+
+Provides functions to build a backup directory path from final_mapping,
+database, and user_config, including workshop/custom backup ID generation
+and .kmmignore rule loading.
+"""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+from typing import Any
+
+from .backup_ops import get_game_backup_id, get_workshop_timestamphex
+from .paths import normalize_posix
+
+
+def get_custom_backup_id(source_paths: list[str]) -> str:
+    """对自定义 mod（无 ACF），取所有源文件的最新 mtime 转为 hex。
+
+    遍历 source_paths，取 max(mtime) → hex。
+    若路径均为空或不存在 → 返回当前时间的 hex。
+
+    Returns:
+        mtime 的小写 hex 字符串
+    """
+    max_mtime: int = 0
+    now = int(time.time())
+
+    for sp in source_paths:
+        p = Path(sp)
+        if p.exists():
+            try:
+                mtime = int(p.stat().st_mtime)
+                if mtime > max_mtime:
+                    max_mtime = mtime
+            except OSError:
+                continue
+
+    if max_mtime == 0:
+        return format(now, "x")
+
+    return format(max_mtime, "x")
+
+
+def build_backup_dirs(
+    final_mapping: list[dict[str, Any]],
+    database: dict[str, Any],
+    user_config: dict[str, Any],
+) -> tuple[dict[str, list[str]], list[str]]:
+    """为 final_mapping 中的每个 app / contentid 构建各自的 backup_dir。
+
+    每个 contentid 独立备份：在各自的根目录下创建 backup dir，
+    backup_id 从对应的 ACF 文件获取。
+
+    Args:
+        final_mapping: mapping 条目列表，每项含 "path" 键
+        database: 含 "game" 列表
+        user_config: 含 "baksuffix" 等
+
+    Returns:
+        ({backup_dir: [file_paths]}, warnings)
+        - backup_dir → 属于该目录的文件绝对路径列表
+        - warnings: 稳定性检查中被跳过的 contentid 警告信息
+    """
+    baksuffix = str(user_config.get("baksuffix", "kmmbackup"))
+
+    # ── 1. 收集所有目标路径 ──────────────────────────────────────────
+    targets: list[str] = []
+    for entry in final_mapping:
+        p = entry.get("path")
+        if p:
+            targets.append(normalize_posix(str(p)))
+
+    if not targets:
+        raise ValueError("E_BACKUP_DIR_BUILD_NO_APPID: final_mapping has no paths")
+
+    # ── 2. 构建 game_entries 索引 ─────────────────────────────────────
+    games = database.get("game", [])
+    game_entries: list[dict[str, Any]] = []
+    for g in games:
+        if not isinstance(g, dict):
+            continue
+        appid = str(g.get("appid", ""))
+        if not appid:
+            continue
+        basepath = str(g.get("basepath", ""))
+        modpath = str(g.get("modpath", ""))
+        if basepath:
+            basepath = normalize_posix(basepath)
+        if modpath:
+            modpath = normalize_posix(modpath)
+        game_entries.append({
+            "appid": appid,
+            "basepath": basepath,
+            "modpath": modpath,
+        })
+
+    # ── 3. 对每个 target，找到匹配的 game entry，分类 ──────────────────
+    # app_hits: {appid: {basepath, files: [paths], steamapps_path}}
+    # content_hits: {(appid, contentid): {modpath, contentid, files: [paths], steamapps_path}}
+    from collections import defaultdict
+
+    app_hits: dict[str, dict] = {}
+    content_hits: dict[tuple[str, str], dict] = {}
+    warnings: list[str] = []
+
+    for target in targets:
+        matched = False
+        for ge in game_entries:
+            # Check basepath (game app, modid==0)
+            if ge["basepath"] and target.startswith(ge["basepath"]):
+                appid = ge["appid"]
+                if appid not in app_hits:
+                    steamapps = normalize_posix(str(Path(ge["basepath"]).parent.parent))
+                    app_hits[appid] = {
+                        "basepath": ge["basepath"],
+                        "files": [],
+                        "steamapps_path": steamapps,
+                    }
+                app_hits[appid]["files"].append(target)
+                matched = True
+                break
+
+            # Check modpath (workshop contentid)
+            if ge["modpath"] and target.startswith(ge["modpath"]):
+                # Extract contentid from path: .../content/{appid}/{contentid}/...
+                appid = ge["appid"]
+                rel = target[len(ge["modpath"]):].lstrip("/")
+                parts = rel.split("/")
+                contentid = parts[0] if parts else ""
+                if contentid:
+                    key = (appid, contentid)
+                    if key not in content_hits:
+                        steamapps = normalize_posix(str(Path(ge["modpath"]).parent.parent.parent))
+                        content_hits[key] = {
+                            "modpath": ge["modpath"],
+                            "contentid": contentid,
+                            "files": [],
+                            "steamapps_path": steamapps,
+                        }
+                    content_hits[key]["files"].append(target)
+                    matched = True
+                    break
+
+        if not matched:
+            warnings.append(f"W_BACKUP_DIR_BUILD_NO_MATCH: {target}")
+
+    # ── 4. 构建 backup_dirs ───────────────────────────────────────────
+    result: dict[str, list[str]] = {}
+
+    # App backups
+    for appid, info in app_hits.items():
+        ok, hex_id, err = get_game_backup_id(info["steamapps_path"], appid)
+        if not ok:
+            warnings.append(err)
+            continue
+        backup_dir = normalize_posix(
+            f"{info['basepath']}/{appid}.{hex_id}.{baksuffix}/"
+        )
+        result[backup_dir] = info["files"]
+
+    # Content backups
+    for (appid, contentid), info in content_hits.items():
+        ok, hex_id, err = get_workshop_timestamphex(
+            info["steamapps_path"], appid, contentid
+        )
+        if not ok:
+            warnings.append(err)
+            continue
+        backup_dir = normalize_posix(
+            f"{info['modpath']}/{contentid}/{contentid}.{hex_id}.{baksuffix}/"
+        )
+        result[backup_dir] = info["files"]
+
+    if not result:
+        raise ValueError("E_BACKUP_DIR_BUILD_NO_APPID: no stable app/contentid found for backup")
+
+    return result, warnings
+
+
+# Keep old function as compatibility wrapper
+def build_backup_dir(
+    final_mapping: list[dict[str, Any]],
+    database: dict[str, Any],
+    user_config: dict[str, Any],
+) -> str:
+    """兼容旧接口：调用 build_backup_dirs 并返回第一个 backup_dir。"""
+    dirs, _warnings = build_backup_dirs(final_mapping, database, user_config)
+    return next(iter(dirs.keys()))
+
+
+def load_dir_suffixes(user_config: dict[str, Any]) -> list[str]:
+    """合并硬编码底线 + user_config.ignore，去重返回目录名后缀列表。
+
+    硬编码底线 ``".kmmbackup"`` 始终在列表中。
+    user_config.ignore 中的条目自动补前导 ``.``（若缺失）。
+    """
+    suffixes = [".kmmbackup"]
+    config_ignore = user_config.get("ignore")
+    if isinstance(config_ignore, list):
+        for item in config_ignore:
+            if isinstance(item, str) and item.strip():
+                s = item.strip()
+                if not s.startswith("."):
+                    s = "." + s
+                if s not in suffixes:
+                    suffixes.append(s)
+    return suffixes
+
+
+__all__ = [
+    "get_custom_backup_id",
+    "get_workshop_timestamphex",
+    "build_backup_dir",
+    "build_backup_dirs",
+    "load_dir_suffixes",
+]