modmgr 0.0.2__tar.gz → 0.0.3__tar.gz

{modmgr-0.0.2/src/modmgr.egg-info → modmgr-0.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modmgr
-Version: 0.0.2
+Version: 0.0.3
 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
@@ -18,15 +18,20 @@ Requires-Dist: uvicorn[standard]>=0.23; extra == "web"
 Dynamic: license-file
 
 ---
-status: active
-concept: readme
-applicable-to: human
-update: 2026-05-20
+Status: active
+Authority: reference-only
+Purpose: readme for beginner
+Read-Tier: never
+Applicable-to: human-only
+Unapplicable-to: agents
+Updated: 2026-06-01
 ---
 
 The Knighthana's Mod Manager
 ============================
 
+作为向最终用户的说明文档省略了内部细节的详细描述，故此**禁止**任何Agent以此作为实现依据；
+
 **项目仍然处于开发阶段，部分核心功能正在深度重构和优化，欢迎开发者加入讨论和贡献，但目前不建议一般用户直接用于生产环境**
 
 探索性开发已告一段落，因个人工作变动，项目短期内将进入低活跃维护状态，欢迎有兴趣的开发者参与。
@@ -57,7 +62,7 @@ The Knighthana's Mod Manager(简称KMM)通过对"文件迁移过程"进行脱离
 pip install modmgr
 
 # 安装 Web 界面（可选）
-pip install modmgr[web]
+pip install "modmgr[web]"
 
 # 启动 Web 服务（需先安装 web 依赖）
 modmgr-web          # → http://127.0.0.1:8000
@@ -73,16 +78,23 @@ modmgr-cli --help
 待程序运行之后，请打开浏览器在[KMM面板](127.0.0.1:8000)进行操作：
 
 1. 在“数据来源”点击“扫描Steam库”等待其完成，这一步是为了创建游戏-MOD数据库；
+![scan_steam_lib](description/ref/webuse03.png)
 2. 在“设置面板”的“规则来源”下方，点击“➕ 添加来源”创建一个新的空行，将Modder交给你的kmmrule文件的路径填写在空行中，点击“保存”；
+![rule_sources](description/ref/webuse04.png)
 3. **务必**点击下方的“保存设置”按钮，对设定进行保存；
 4. 进入“工作区”页面，点击右上方的“新建工作区”，输入必要的信息来创建一个工作区，每个工作区各自保存了一种替换模式，尽可能为每类不同的任务创建不同的工作区；
+![work_save_space1](description/ref/webuse01.png) ![work_save_space2](description/ref/webuse02.png)
 5. 在面板中点击工作区条目的“进入”来进入一个工作区；
 6. 在“发现的规则文件”勾选Modder提供给你的kmmrule文件前方的复选框，如果感兴趣可以点击右侧的“展开”以查看这个规则的详细信息；
+![select_rules](description/ref/webuse05.png)
 7. 点击“进入计算准备”，系统会自动将你导航到“计算准备”页面；
 8. 仅保留想要替换的库/游戏/MOD前方的复选框，之后点击“开始计算”或者“计算查看”；复选框用于确定实际影响的游戏/MOD，可见按钮仅仅用于调整视觉效果，不影响最终结果；
+![prepare_for_compute](description/ref/webuse06.png)
 9. 自行点击或等待系统导航进入“森林可视”界面，可以放大映射图，检查这些映射是不是你所想要的；
+![forest_view](description/ref/webuse07.png)
 10. 如果有必要，在“冲突裁决”页面进行手动裁决；
 11. 进入“文件操作”页面，如果这是首次操作，必须先点击“备份”，如果心存疑虑，务必打开"dry run"开关进行模拟；"dry run"不会进行任何实际的文件操作；
+![file_operation](description/ref/webuse08.png)
 12. “备份”完成后，可以点击“应用”进行文件替换，等待操作完成；
 13. 如果您的游戏/MOD需要分时间使用多个不同的规则，那么下次请在“备份”前先点击“恢复”，然后再“备份”和“应用”；
 
@@ -101,7 +113,7 @@ modmgr-cli --help
 |---|------|-------|-----|
 |用户配置|`~/.config/kmm/`|`%APPDATA%/kmm/`|`~/Library/Preferences/kmm/`|
 |默认数据库|`~/.local/share/kmm/`|`%LOCALAPPDATA%/kmm/database/`|`~/Library/Application Support/kmm/`|
-|默认工作区|`~/.cache/kmm/workspace/`|`%LOCALAPPDATA%/kmm/workspace/`|`%LOCALAPPDATA%/kmm/workspace/`|
+|默认工作区|`~/.cache/kmm/workspace/`|`%LOCALAPPDATA%/kmm/workspace/`|`~/Library/Caches/`|
 
 这些值是硬编码的“默认值”，但目前也支持通过“设置面板”进行自定义；
 
@@ -130,6 +142,8 @@ modmgr-cli --help
 
 项目还在成长，接受各种想法；
 
+---------------------------
+
 Knighthana
 
 2026/05/22

{modmgr-0.0.2 → modmgr-0.0.3}/README.md

@@ -1,13 +1,18 @@
 ---
-status: active
-concept: readme
-applicable-to: human
-update: 2026-05-20
+Status: active
+Authority: reference-only
+Purpose: readme for beginner
+Read-Tier: never
+Applicable-to: human-only
+Unapplicable-to: agents
+Updated: 2026-06-01
 ---
 
 The Knighthana's Mod Manager
 ============================
 
+作为向最终用户的说明文档省略了内部细节的详细描述，故此**禁止**任何Agent以此作为实现依据；
+
 **项目仍然处于开发阶段，部分核心功能正在深度重构和优化，欢迎开发者加入讨论和贡献，但目前不建议一般用户直接用于生产环境**
 
 探索性开发已告一段落，因个人工作变动，项目短期内将进入低活跃维护状态，欢迎有兴趣的开发者参与。
@@ -38,7 +43,7 @@ The Knighthana's Mod Manager(简称KMM)通过对"文件迁移过程"进行脱离
 pip install modmgr
 
 # 安装 Web 界面（可选）
-pip install modmgr[web]
+pip install "modmgr[web]"
 
 # 启动 Web 服务（需先安装 web 依赖）
 modmgr-web          # → http://127.0.0.1:8000
@@ -54,16 +59,23 @@ modmgr-cli --help
 待程序运行之后，请打开浏览器在[KMM面板](127.0.0.1:8000)进行操作：
 
 1. 在“数据来源”点击“扫描Steam库”等待其完成，这一步是为了创建游戏-MOD数据库；
+![scan_steam_lib](description/ref/webuse03.png)
 2. 在“设置面板”的“规则来源”下方，点击“➕ 添加来源”创建一个新的空行，将Modder交给你的kmmrule文件的路径填写在空行中，点击“保存”；
+![rule_sources](description/ref/webuse04.png)
 3. **务必**点击下方的“保存设置”按钮，对设定进行保存；
 4. 进入“工作区”页面，点击右上方的“新建工作区”，输入必要的信息来创建一个工作区，每个工作区各自保存了一种替换模式，尽可能为每类不同的任务创建不同的工作区；
+![work_save_space1](description/ref/webuse01.png) ![work_save_space2](description/ref/webuse02.png)
 5. 在面板中点击工作区条目的“进入”来进入一个工作区；
 6. 在“发现的规则文件”勾选Modder提供给你的kmmrule文件前方的复选框，如果感兴趣可以点击右侧的“展开”以查看这个规则的详细信息；
+![select_rules](description/ref/webuse05.png)
 7. 点击“进入计算准备”，系统会自动将你导航到“计算准备”页面；
 8. 仅保留想要替换的库/游戏/MOD前方的复选框，之后点击“开始计算”或者“计算查看”；复选框用于确定实际影响的游戏/MOD，可见按钮仅仅用于调整视觉效果，不影响最终结果；
+![prepare_for_compute](description/ref/webuse06.png)
 9. 自行点击或等待系统导航进入“森林可视”界面，可以放大映射图，检查这些映射是不是你所想要的；
+![forest_view](description/ref/webuse07.png)
 10. 如果有必要，在“冲突裁决”页面进行手动裁决；
 11. 进入“文件操作”页面，如果这是首次操作，必须先点击“备份”，如果心存疑虑，务必打开"dry run"开关进行模拟；"dry run"不会进行任何实际的文件操作；
+![file_operation](description/ref/webuse08.png)
 12. “备份”完成后，可以点击“应用”进行文件替换，等待操作完成；
 13. 如果您的游戏/MOD需要分时间使用多个不同的规则，那么下次请在“备份”前先点击“恢复”，然后再“备份”和“应用”；
 
@@ -82,7 +94,7 @@ modmgr-cli --help
 |---|------|-------|-----|
 |用户配置|`~/.config/kmm/`|`%APPDATA%/kmm/`|`~/Library/Preferences/kmm/`|
 |默认数据库|`~/.local/share/kmm/`|`%LOCALAPPDATA%/kmm/database/`|`~/Library/Application Support/kmm/`|
-|默认工作区|`~/.cache/kmm/workspace/`|`%LOCALAPPDATA%/kmm/workspace/`|`%LOCALAPPDATA%/kmm/workspace/`|
+|默认工作区|`~/.cache/kmm/workspace/`|`%LOCALAPPDATA%/kmm/workspace/`|`~/Library/Caches/`|
 
 这些值是硬编码的“默认值”，但目前也支持通过“设置面板”进行自定义；
 
@@ -111,6 +123,8 @@ modmgr-cli --help
 
 项目还在成长，接受各种想法；
 
+---------------------------
+
 Knighthana
 
 2026/05/22

{modmgr-0.0.2 → modmgr-0.0.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "modmgr"
-version = "0.0.2"
+version = "0.0.3"
 description = "File mapping and backup rule engine for workshop mods"
 requires-python = ">=3.10"
 keywords = ["mod", "manager", "game", "backup"]

{modmgr-0.0.2 → modmgr-0.0.3}/src/modmgr/__init__.py

@@ -1,4 +1,4 @@
-"""modmanager package."""
+"""modmgr package."""
 
 __all__ = [
     "engine",

{modmgr-0.0.2 → modmgr-0.0.3}/src/modmgr/acf_parser.py

@@ -116,34 +116,6 @@ def parse_appworkshop_acf(acf_path: str) -> list[dict[str, Any]]:
     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 字段并返回字符串。
 
@@ -295,8 +267,6 @@ def get_workshop_latest_timeupdated(steamapps_path: str, appid: str, contentid:
 __all__ = [
     "parse_appmanifest_acf",
     "parse_appworkshop_acf",
-    "find_appmanifest_acf_files",
-    "find_appworkshop_acf_files",
     "get_workshop_timeupdated",
     "get_workshop_latest_timeupdated",
 ]

{modmgr-0.0.2 → modmgr-0.0.3}/src/modmgr/apply_ops.py

@@ -45,6 +45,11 @@ def apply_entries(
             target_path = entry["path"]
             request = entry.get("request")
 
+            if not target_path:
+                errors.append(f"E_APPLY_MISSING_TARGET: apply entry has empty target path")
+                finished += 1
+                continue
+
             if request is None:
                 skipped.append({"path": target_path, "reason": "no source (vacuous node)"})
                 finished += 1
@@ -61,8 +66,10 @@ def apply_entries(
 
             try:
                 if action == "delete":
+                    # File-to-file guard in BOTH modes so dry_run reports
+                    # the same errors the real run would
+                    _assert_is_file(target_path, action)
                     if not dry_run:
-                        _assert_is_file(target_path, action)
                         os.remove(target_path)
                     applied.append({
                         "action": "delete",
@@ -78,6 +85,17 @@ def apply_entries(
                         finished += 1
                         continue
 
+                    # Existence + file-type checks in BOTH modes so dry_run
+                    # reports the same errors the real run would (§6.2)
+                    if os.path.isdir(source_path):
+                        errors.append(f"E_APPLY_DIRECTORY_NOT_ALLOWED: {action} source is a directory: {source_path}")
+                        finished += 1
+                        continue
+                    if not os.path.isfile(source_path):
+                        errors.append(f"E_APPLY_MISSING_SOURCE: {source_path}")
+                        finished += 1
+                        continue
+
                     if not dry_run:
                         _assert_is_file(source_path, action)
                         os.makedirs(os.path.dirname(target_path), exist_ok=True)

{modmgr-0.0.2 → modmgr-0.0.3}/src/modmgr/backup_dir_builder.py

@@ -63,7 +63,7 @@ def build_backup_dirs(
         - backup_dir → 属于该目录的文件绝对路径列表
         - warnings: 稳定性检查中被跳过的 contentid 警告信息
     """
-    baksuffix = str(user_config.get("baksuffix", "kmmbackup"))
+    baksuffix = str(user_config.get("baksuffix"))
 
     # ── 1. 收集所有目标路径 ──────────────────────────────────────────
     targets: list[str] = []
@@ -190,23 +190,13 @@ def build_backup_dir(
     return next(iter(dirs.keys()))
 
 
-def load_dir_suffixes(user_config: dict[str, Any]) -> list[str]:
-    """合并硬编码底线 + user_config.ignore，去重返回目录名后缀列表。
+def load_dir_suffixes() -> list[str]:
+    """返回硬编码的目录名后缀列表。
 
-    硬编码底线 ``".kmmbackup"`` 始终在列表中。
-    user_config.ignore 中的条目自动补前导 ``.``（若缺失）。
+    始终包含 ``".kmmbackup"``。
+    kmmignore 规则仅来自 ``.kmmignore`` 文件，不再通过此函数读取。
     """
-    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
+    return [".kmmbackup"]
 
 
 __all__ = [