modmgr 0.0.1__tar.gz

modmgr-0.0.1/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2025-2026 Knighthana
+
+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.

modmgr-0.0.1/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: modmgr
+Version: 0.0.1
+Summary: File mapping and backup rule engine for workshop mods
+Project-URL: Homepage, https://github.com/Knighthana/modmanager
+Project-URL: Repository, https://github.com/Knighthana/modmanager
+Project-URL: Issues, https://github.com/Knighthana/modmanager/issues
+Keywords: mod,manager,game,backup
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown; charset=UTF-8
+License-File: LICENSE
+Requires-Dist: vdf>=0.4.0
+Requires-Dist: jsonschema>=3.2.0
+Requires-Dist: gitignore-parser>=0.1.0
+Provides-Extra: web
+Requires-Dist: fastapi>=0.100; extra == "web"
+Requires-Dist: uvicorn[standard]>=0.23; extra == "web"
+Dynamic: license-file
+
+---
+status: active
+concept: readme
+applicable-to: human
+update: 2026-05-20
+---
+
+The Knighthana's Mod Manager
+============================
+
+This repository provides the full source tree, including the frontend and build tooling.
+For PyPI, the current release path is intentionally narrower: install the core package first,
+and use GitHub for the full web-enabled development experience.
+
+# 简介
+
+The Knighthana's Mod Manager(简称KMM)通过对"文件迁移过程"进行脱离具体环境的语义化定义和简单执行，实现对MOD->本体，MOD->MOD，还包括诸如MOD->MOD->MOD->本体这样嵌套方式的支持；
+
+并且针对具体的替换规则，实现原文件的备份保护和按需还原；
+
+作为“文件操作语义定义与管理”的雏形想法，这个项目初期在Steam游戏本体<->Steam创意工坊这样的环境上进行实践；
+
+# 作为普通用户
+
+如果你希望获得完整的 Web 界面和前端源码，请直接使用本仓库的 GitHub 版本。
+如果你只是想先通过 PyPI 安装核心能力，目前发布物会优先保证 CLI / 后端逻辑可用。
+
+如果要作为普通用户使用这个项目，请前往[release]()页面，下载符合自己系统平台的分发文件，遵守指引安装；
+
+待程序运行之后，请打开浏览器在[KMM面板](127.0.0.1:8000)进行操作：
+
+1. 在“数据来源”点击“扫描Steam库”等待其完成，这步是为了创建游戏-MOD数据库；
+2. 在“设置面板”的“规则来源”下方，点击“➕ 添加来源”创建一个新的空行，将Modder交给你的kmmrule文件的路径填写在空行中，点击“保存”；
+3. **务必**点击下方的“保存设置”按钮，对设定进行保存；
+4. 进入“工作区”页面，点击右上方的“新建工作区”，输入必要的信息来创建一个工作区，每个工作区各自保存了一种替换模式，尽可能为每类不同的任务创建不同的工作区；
+5. 在面板中点击工作区条目的“进入”来进入一个工作区；
+6. 在“发现的规则文件”勾选Modder提供给你的kmmrule文件前方的复选框，如果感兴趣可以点击右侧的“展开”以查看这个规则的详细信息；
+7. 点击“进入计算准备”，系统会自动将你导航到“计算准备”页面；
+8. 仅保留想要替换的库/游戏/MOD前方的复选框，之后点击“开始计算”或者“计算查看”；复选框用于确定实际影响的游戏/MOD，可见按钮仅仅用于调整视觉效果，不影响最终结果；
+9. 自行点击或等待系统导航进入“森林可视”界面，可以放大映射图，检查这些映射是不是你所想要的；
+10. 如果有必要，在“冲突裁决”页面进行手动裁决；
+11. 进入“文件操作”页面，如果这是首次操作，必须先点击“备份”，如果心存疑虑，务必打开"dry run"开关进行模拟；"dry run"不会进行任何实际的文件操作；
+12. “备份”完成后，可以点击“应用”进行文件替换，等待操作完成；
+13. 如果您的游戏/MOD需要分时间使用多个不同的规则，那么下次请在“备份”前先点击“恢复”，然后再“备份”和“应用”；
+
+## 注意事项
+
+本项目采用“懒备份”和“蠢还原”两个原则进行文件管理，它不会也不应该推测当前目录中文件的来源，备份时永远假定当前状态是需要被记录的快照，还原时只对比外部文件与备份文件之间的相似度，因此：
+
+- 仅在文件目录处于“被Steam验证后”的“原始状态”时，才使用“备份”功能；
+- 若当前文件已经是“应用”之后的样子，务必在下一次切换规则前，**使用“恢复”功能**使目录恢复原状，才能开始下一次“备份”和“替换”作业；
+
+# 作为Modder
+
+如果想要快速上手，请参考`description/kmm_rule_RWR-khn_CT-castears-z2414_Replace.json.example`撰写自己的kmmrule规则文件；
+
+如果有一定的软件开发基础，或者对产出有更高的要求，更加建议参考`repo_spec/`中的schema文件，或者具体的代码实现，撰写更加安全和灵活的kmmrule规则文件；
+
+在分发Mod时，建议同时分发kmmrule文件和本项目的链接，指引用户通过kmmrule进行规则化的MOD安装；
+
+# 作为开发者
+
+欢迎为本项目贡献代码；
+
+目前项目已经确定的未来方向是：
+
+- 迁移到[Tauri2](https://v2.tauri.app/zh-cn/)，提供更加定制化的GUI方便使用；
+- 完善“规则制定”页面，方便kmmrule文件的制定；
+- 进行内部资源传递优化方案，初步便于readme和preview的展示，之后还可灵活应用于其它外部资源；
+- 将项目脱离SteamWorks场景使用，用于其他游戏MOD文件的管理；
+- 实现对任意类型目录任意文件的管理，或是应用于嵌入式设备中进行资源敏感场合的文件管理；
+- 脱离“文件系统”场景，允许后端接驳Redis等广泛意义上的“资源provider”；
+
+欢迎提出更多的想法，比如“我想用它管理Minecraft模组”，或者“我想用它管理我的本地音乐收藏”，或者“我有一个嵌入式设备中需要这样的管理器对规则集合进行管理”；
+
+项目还在成长，接受各种想法；

modmgr-0.0.1/README.md

@@ -0,0 +1,76 @@
+---
+status: active
+concept: readme
+applicable-to: human
+update: 2026-05-20
+---
+
+The Knighthana's Mod Manager
+============================
+
+This repository provides the full source tree, including the frontend and build tooling.
+For PyPI, the current release path is intentionally narrower: install the core package first,
+and use GitHub for the full web-enabled development experience.
+
+# 简介
+
+The Knighthana's Mod Manager(简称KMM)通过对"文件迁移过程"进行脱离具体环境的语义化定义和简单执行，实现对MOD->本体，MOD->MOD，还包括诸如MOD->MOD->MOD->本体这样嵌套方式的支持；
+
+并且针对具体的替换规则，实现原文件的备份保护和按需还原；
+
+作为“文件操作语义定义与管理”的雏形想法，这个项目初期在Steam游戏本体<->Steam创意工坊这样的环境上进行实践；
+
+# 作为普通用户
+
+如果你希望获得完整的 Web 界面和前端源码，请直接使用本仓库的 GitHub 版本。
+如果你只是想先通过 PyPI 安装核心能力，目前发布物会优先保证 CLI / 后端逻辑可用。
+
+如果要作为普通用户使用这个项目，请前往[release]()页面，下载符合自己系统平台的分发文件，遵守指引安装；
+
+待程序运行之后，请打开浏览器在[KMM面板](127.0.0.1:8000)进行操作：
+
+1. 在“数据来源”点击“扫描Steam库”等待其完成，这步是为了创建游戏-MOD数据库；
+2. 在“设置面板”的“规则来源”下方，点击“➕ 添加来源”创建一个新的空行，将Modder交给你的kmmrule文件的路径填写在空行中，点击“保存”；
+3. **务必**点击下方的“保存设置”按钮，对设定进行保存；
+4. 进入“工作区”页面，点击右上方的“新建工作区”，输入必要的信息来创建一个工作区，每个工作区各自保存了一种替换模式，尽可能为每类不同的任务创建不同的工作区；
+5. 在面板中点击工作区条目的“进入”来进入一个工作区；
+6. 在“发现的规则文件”勾选Modder提供给你的kmmrule文件前方的复选框，如果感兴趣可以点击右侧的“展开”以查看这个规则的详细信息；
+7. 点击“进入计算准备”，系统会自动将你导航到“计算准备”页面；
+8. 仅保留想要替换的库/游戏/MOD前方的复选框，之后点击“开始计算”或者“计算查看”；复选框用于确定实际影响的游戏/MOD，可见按钮仅仅用于调整视觉效果，不影响最终结果；
+9. 自行点击或等待系统导航进入“森林可视”界面，可以放大映射图，检查这些映射是不是你所想要的；
+10. 如果有必要，在“冲突裁决”页面进行手动裁决；
+11. 进入“文件操作”页面，如果这是首次操作，必须先点击“备份”，如果心存疑虑，务必打开"dry run"开关进行模拟；"dry run"不会进行任何实际的文件操作；
+12. “备份”完成后，可以点击“应用”进行文件替换，等待操作完成；
+13. 如果您的游戏/MOD需要分时间使用多个不同的规则，那么下次请在“备份”前先点击“恢复”，然后再“备份”和“应用”；
+
+## 注意事项
+
+本项目采用“懒备份”和“蠢还原”两个原则进行文件管理，它不会也不应该推测当前目录中文件的来源，备份时永远假定当前状态是需要被记录的快照，还原时只对比外部文件与备份文件之间的相似度，因此：
+
+- 仅在文件目录处于“被Steam验证后”的“原始状态”时，才使用“备份”功能；
+- 若当前文件已经是“应用”之后的样子，务必在下一次切换规则前，**使用“恢复”功能**使目录恢复原状，才能开始下一次“备份”和“替换”作业；
+
+# 作为Modder
+
+如果想要快速上手，请参考`description/kmm_rule_RWR-khn_CT-castears-z2414_Replace.json.example`撰写自己的kmmrule规则文件；
+
+如果有一定的软件开发基础，或者对产出有更高的要求，更加建议参考`repo_spec/`中的schema文件，或者具体的代码实现，撰写更加安全和灵活的kmmrule规则文件；
+
+在分发Mod时，建议同时分发kmmrule文件和本项目的链接，指引用户通过kmmrule进行规则化的MOD安装；
+
+# 作为开发者
+
+欢迎为本项目贡献代码；
+
+目前项目已经确定的未来方向是：
+
+- 迁移到[Tauri2](https://v2.tauri.app/zh-cn/)，提供更加定制化的GUI方便使用；
+- 完善“规则制定”页面，方便kmmrule文件的制定；
+- 进行内部资源传递优化方案，初步便于readme和preview的展示，之后还可灵活应用于其它外部资源；
+- 将项目脱离SteamWorks场景使用，用于其他游戏MOD文件的管理；
+- 实现对任意类型目录任意文件的管理，或是应用于嵌入式设备中进行资源敏感场合的文件管理；
+- 脱离“文件系统”场景，允许后端接驳Redis等广泛意义上的“资源provider”；
+
+欢迎提出更多的想法，比如“我想用它管理Minecraft模组”，或者“我想用它管理我的本地音乐收藏”，或者“我有一个嵌入式设备中需要这样的管理器对规则集合进行管理”；
+
+项目还在成长，接受各种想法；

modmgr-0.0.1/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "modmgr"
+version = "0.0.1"
+description = "File mapping and backup rule engine for workshop mods"
+requires-python = ">=3.10"
+keywords = ["mod", "manager", "game", "backup"]
+dependencies = [
+    "vdf>=0.4.0",
+    "jsonschema>=3.2.0",
+    "gitignore-parser>=0.1.0",
+]
+
+[project.readme]
+file = "README.md"
+content-type = "text/markdown; charset=UTF-8"
+
+[project.scripts]
+modmgr-cli = "hana_modmgr.cli:main"
+
+[project.optional-dependencies]
+web = [
+    "fastapi>=0.100",
+    "uvicorn[standard]>=0.23",
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[project.urls]
+Homepage = "https://github.com/Knighthana/modmanager"
+Repository = "https://github.com/Knighthana/modmanager"
+Issues = "https://github.com/Knighthana/modmanager/issues"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

modmgr-0.0.1/setup.cfg

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

modmgr-0.0.1/src/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-0.0.1/src/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",
+]