diff --git a/README.md b/README.md index 03ad753..b965ce1 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,31 @@ Python toolchain for managing Arma 3 mod presets: parse launcher exports, compar --- +## Quick Reference + +```bash +# First time setup +cp config.template.json config.json # fill in server URL + credentials + arma_dir +python check_deps.py # verify dependencies + +# Day-to-day: full pipeline +python run.py # parse → compare → download → link + +# GUI (recommended) +python gui.py + +# Maintenance +python clean_orphans.py --dry-run # find stale mod folders from old presets +python update_mods.py # re-download changed files (size-check) +python sync_missing.py # retry mods that were absent from server +python check_names.py --fix # fix folder name mismatches + +# Testing +python test_suite.py # 142 tests (network tests auto-skip if offline) +``` + +--- + ## Table of Contents 1. [Prerequisites](#prerequisites) @@ -20,6 +45,7 @@ Python toolchain for managing Arma 3 mod presets: parse launcher exports, compar - [sync_missing.py](#sync_missingpy) - [update_mods.py](#update_modspy) - [check_names.py](#check_namespy) + - [clean_orphans.py](#clean_orphanspy) - [run.py](#runpy) - [gui.py](#guipy) 6. [Migrating Existing Mods](#migrating-existing-mods) @@ -468,6 +494,36 @@ python check_names.py --fix --fix-ids --- +### clean_orphans.py + +Find and optionally delete orphaned mod folders — `downloads/{group}/@ModName` folders that are no longer referenced in `comparison.json`. These accumulate when you switch presets and re-run the pipeline without cleaning up old downloads. + +```bash +python clean_orphans.py # list orphans, prompt for confirmation +python clean_orphans.py --dry-run # list orphans, do not delete +python clean_orphans.py --yes # list and delete without prompting +``` + +``` + Group Folder Size + ---------------------------- -------------------------------- ---------- + shared @OldMod 124.5 MB + 150th_WW2_2026_V1.0 @SomeMod 88.2 MB + + 2 orphan(s) found — 212.7 MB total + + Delete all orphans? [y/N] +``` + +- Matches by normalized name (same logic as the fetcher), so spacing/capitalization differences are handled correctly +- Junction-safe: uses `os.rmdir()` on junctions rather than `shutil.rmtree` to avoid deleting target files + +**Requires:** `modlist_json/comparison.json` (run `run.py --skip-fetch --skip-link` first). + +The same functionality is available as the **Clean Orphans** tab in the GUI. + +--- + ### run.py Orchestrator that chains all four pipeline steps. Described in [Quick Start](#quick-start--full-pipeline) above. @@ -488,10 +544,12 @@ Opens a CustomTkinter desktop window with a sidebar navigation and the following |------|---------| | Dashboard | Overview: status, quick stats, recent activity | | Mods | Browse and manage downloaded mods by group | -| Tools | Link/unlink, rename, sync missing, check server | +| Tools | Link/unlink, rename, sync missing, check server, **clean orphans** | | Logs | Real-time log output from pipeline operations | | Settings | Edit `config.json` (server URL, paths, credentials) | +The **Tools** view has five tabs: Check Names, Update Mods, Link Mods, Sync Missing / Report Missing, and **Clean Orphans** (find and delete stale mod folders from old presets). + On first launch (no `config.json`), a setup wizard walks you through creating one. **Requires:** `customtkinter` (`pip install customtkinter`). @@ -543,6 +601,7 @@ arma-modlist-tools/ | |- fetcher.py # Caddy server downloader | |- linker.py # Junction/symlink manager | |- reporter.py # Missing-mod report builder +| |- cleaner.py # Orphan folder detection | |- config.py # config.json loader | |- compat.py # OS detection + encoding fix | @@ -591,8 +650,9 @@ arma-modlist-tools/ |- sync_missing.py # Sync newly available missing mods |- update_mods.py # Re-download updated mod files |- check_names.py # Diagnose and fix folder name / steam_id issues +|- clean_orphans.py # Find and delete orphaned mod folders |- check_deps.py # Dependency checker -|- test_suite.py # Test suite +|- test_suite.py # Test suite (142 tests) ``` --- @@ -631,7 +691,7 @@ arma-modlist-tools/ ## Running Tests -The test suite covers all modules with 96 tests. No network connection required. +The test suite covers all modules with 142 tests. Network tests (section 15) auto-skip when the server is unreachable. ```bash python test_suite.py @@ -639,19 +699,21 @@ python test_suite.py ``` ------------------------------------------------------------ - compat 6 tests - config 5 tests - parser 9 tests - compare 8 tests - fetcher 19 tests (pure functions, no network) - reporter 8 tests - linker 12 tests (uses temp dirs) - __init__ 2 tests - check_names 16 tests - integration 2 tests - gui._io 11 tests (QueueWriter, no GUI required) + compat 11 tests + config 5 tests + parser 9 tests + compare 8 tests + fetcher 24 tests (pure functions + mock) + reporter 8 tests + linker 12 tests (uses temp dirs) + __init__ 2 tests + check_names 16 tests + integration 2 tests + gui._io 11 tests (QueueWriter, no GUI required) + cleaner 8 tests + e2e — clean_orphans 6 tests (subprocess CLI) + coverage gaps 23 tests (mocked platform branches) + live server 9 tests (skipped if server unreachable) ------------------------------------------------------------ - Results: 95 passed, 1 failed, 0 skipped (96 total) + Results: 142 passed, 0 failed, 0 skipped (142 total) ``` - -> The 1 failing test is a pre-existing comparison snapshot mismatch unrelated to the GUI changes. diff --git a/docs/huong-dan-su-dung.md b/docs/huong-dan-su-dung.md index 5cd6cf1..81413ac 100644 --- a/docs/huong-dan-su-dung.md +++ b/docs/huong-dan-su-dung.md @@ -13,6 +13,11 @@ Tài liệu này dành cho người dùng **chưa biết gì** về dự án. B 5. [Tổng quan (Dashboard) — Quy trình cơ bản](#5-tổng-quan-dashboard--quy-trình-cơ-bản) 6. [Danh sách Mod](#6-danh-sách-mod) 7. [Công cụ nâng cao](#7-công-cụ-nâng-cao) + - [Check Names](#tab-check-names--kiểm-tra-tên-thư-mục) + - [Update Mods](#tab-update-mods--cập-nhật-mod) + - [Link Mods](#tab-link-mods--quản-lý-liên-kết) + - [Sync / Report Missing](#tab-sync-missing--đồng-bộ-mod-thiếu) + - [Clean Orphans](#tab-clean-orphans--dọn-dẹp-mod-thừa) 8. [Nhật ký (Logs)](#8-nhật-ký-logs) 9. [Cài đặt](#9-cài-đặt) 10. [Đổi sang giao diện tiếng Việt](#10-đổi-sang-giao-diện-tiếng-việt) @@ -212,6 +217,14 @@ Gõ vào ô **Tìm kiếm:** để lọc mod theo tên trong tab đang xem. Trang **Công cụ** có 5 tab phụ cho các tác vụ bảo trì. Mỗi tab đều có nút chạy ở góc phải phía dưới, output hiển thị trong **Nhật ký**. +| Tab | Chức năng tóm tắt | +|-----|-------------------| +| Check Names | Kiểm tra và sửa tên thư mục mod | +| Update Mods | Tải lại tệp mod đã thay đổi trên máy chủ | +| Link Mods | Tạo / xóa junction tới Arma 3 Server | +| Sync / Report Missing | Đồng bộ và báo cáo mod còn thiếu | +| **Clean Orphans** | Xóa thư mục mod thừa từ preset cũ | + ### Tab "Check Names" — Kiểm tra tên thư mục Quét thư mục mod trên máy tính và so sánh với máy chủ. Báo cáo các vấn đề: @@ -254,6 +267,22 @@ Thử tải lại các mod bị thiếu từ lần chạy pipeline trước. H Kiểm tra mod nào trong `comparison.json` chưa có trên máy chủ và lưu báo cáo vào `missing_report.json`. Dùng để theo dõi mod cần yêu cầu admin bổ sung. +### Tab "Clean Orphans" — Dọn dẹp mod thừa + +Khi bạn đổi preset và chạy lại pipeline, các mod của preset cũ vẫn còn trong thư mục `downloads/` nhưng không được dùng nữa — gọi là **mod thừa** (orphan). Tab này giúp tìm và xóa chúng để giải phóng dung lượng ổ đĩa. + +**Cách dùng:** + +1. Nhấn **Quét mod thừa** — ứng dụng sẽ so sánh thư mục `downloads/` với `comparison.json` hiện tại +2. Danh sách mod thừa hiện ra kèm tên nhóm và dung lượng +3. Dùng **Chọn tất cả** hoặc tick thủ công từng mục +4. Nhấn **Xóa đã chọn** — xuất hiện hộp thoại xác nhận +5. Nhấn **Xác nhận xóa** để thực hiện; danh sách sẽ tự động quét lại sau khi xóa + +> **Lưu ý an toàn:** Ứng dụng chỉ xóa thư mục `@ModName` trong `downloads/`, không đụng tới thư mục Arma 3 Server. Junction (liên kết) sẽ bị xóa đúng cách mà không làm mất tệp gốc. + +**Yêu cầu:** Cần có `comparison.json` (chạy pipeline ít nhất một lần trước). + --- ## 8. Nhật ký (Logs) @@ -372,8 +401,9 @@ Hiển thị các đường dẫn đang dùng: URL máy chủ, thư mục Arma, | **comparison.json** | Tệp kết quả so sánh preset, lưu danh sách mod theo nhóm | | **missing_report.json** | Báo cáo mod có trong preset nhưng chưa có trên máy chủ | | **downloads/** | Thư mục chứa tệp mod đã tải về | +| **Mod thừa (Orphan)** | Thư mục mod còn trong `downloads/` nhưng không còn trong preset nào đang dùng | | **config.json** | Tệp cấu hình lưu thông tin máy chủ và đường dẫn | --- -*Phiên bản tài liệu: 2026-04. Nếu có vấn đề, liên hệ người quản trị máy chủ.* +*Phiên bản tài liệu: 2026-04 (cập nhật: thêm Clean Orphans). Nếu có vấn đề, liên hệ người quản trị máy chủ.*