windy/dl-organizer
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs sync post-refactor baseline

Browse Source
This commit is contained in:
windyboy
2026-04-07 11:07:01 +08:00
parent 0a6bddcc7e
commit c9d22d5136
14 changed files with 75 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files
GEMINI.md
+8 -6
View File
@@ -1,7 +1,7 @@
# GEMINI.md
## Documentation Status
- Synced with repository refactor baseline on 2026-02-20 (source of truth: `CHANGELOG.md`).
- Synced with the post-refactor baseline on 2026-04-07 (source of truth: `CHANGELOG.md`).
This document provides a comprehensive overview of the Video Library Manager (VLM) project, intended to be used as instructional context for Gemini.
@@ -14,8 +14,8 @@ The Video Library Manager (VLM) is a Python-based CLI tool designed for managing
* **Scanning & Parsing:** Discovers video files, extracts metadata. Proactively detects `ffprobe` for video properties with graceful fallback to file-level metadata. Parses filenames for titles, years, seasons, and episodes, with specific support for Anime-style hyphenated numbering and release group stripping.
* **Metadata Enrichment:** Augments local data with information from TMDB, including bilingual titles and reputation scores. It uses a local SQLite cache to improve performance.
* **Analysis:** Detects duplicate files (with quality comparisons) and identifies gaps in TV series episodes.
* **Planning & Execution:** Generates a reviewable JSON-based execution plan for file operations (move, rename, quarantine). Supports "safe mode" and directory preservation.
* **Plan Review Cycle:** Exports high-risk operations to CSV for manual confirmation (`review-plan`) and synchronizes user decisions back to the master plan (`apply-review`), enabling a full human-in-the-loop workflow.
* **Planning & Execution:** Generates a reviewable JSON-based execution plan for file operations (move, rename, quarantine), validates move/rename sources and destinations against `library_root` during execution, and keeps execution failures isolated per operation.
* **Plan Review Cycle:** Exports high-risk operations to CSV for manual confirmation (`review-plan`), offers an optional Textual TUI via `review-plan --tui`, and synchronizes user decisions back to the master plan (`apply-review`).
* **Quarantine Management:** Safely isolates files for review, with full support for listing and restoration.
* **Reporting:** Creates reports for inventory, duplicate files, and series completeness.
* **State Management:** Tracks the status of files throughout the organization workflow.
@@ -36,16 +36,15 @@ The project follows a modular structure located in the `src/vlm` directory.
* `cli.py`: The main entry point for the CLI, using Click.
* `commands/*.py`: Implementation of the individual CLI commands (scan, parse, enrich, analyze, plan, execute/rollback).
* `scanner.py`, `parser.py`, `enrichment.py`, `analysis.py`, `planner.py`, `executor.py`: Core logic for the different stages of the workflow.
* `io.py`: Unified I/O layer for JSON and CSV handling.
* `io.py`: Unified I/O layer for JSON and CSV handling, including validated typed plan loading.
* `cache.py`: Local SQLite cache for TMDB metadata.
* `context.py`: CLI context and state management for command execution.
* `duplicate_resolve.py`: Logic for resolving duplicate files based on quality and metadata.
* `duplicate_resolve.py`: Logic for resolving duplicate files with explicit failure on unsupported or ambiguous inputs.
* `logging_config.py`: Centralized logging configuration.
* `plan_review.py`: Risk analysis and manual review generation for execution plans.
* `quarantine.py`: Management of quarantined files (listing, adding, restoring).
* `reports.py`: Generation of inventory, completeness, and duplicate reports.
* `state.py`: File status tracking and persistence (reviewed, ignored, planned, etc.).
* `transaction.py`: Atomic filesystem operations and transaction logging for reliability.
* `providers/tmdb.py`: Client for interacting with the TMDB API.
* `models.py`: Defines the data structures used throughout the application.
* `config.py`: Manages application configuration from a YAML file.
@@ -59,6 +58,7 @@ The project uses `uv` for dependency management.
* Install dependencies: `uv pip install -e .`
* Install development dependencies: `uv pip install -e ".[dev]"`
* Install the optional Textual review UI: `uv pip install -e ".[tui]"`
**Running the application:**
@@ -71,6 +71,8 @@ The main entry point is the `vlm` command.
* Analyze the library: `uv run vlm analyze`
* Generate a plan: `uv run vlm plan`
* Review a plan: `uv run vlm review-plan`
* Review a plan in the optional TUI: `uv run vlm review-plan --tui`
* Apply edited review CSV decisions: `uv run vlm apply-review`
* Execute the plan (dry-run): `uv run vlm execute`
* Execute the plan (with confirmation): `uv run vlm execute --confirm`
* Rollback the last execution: `uv run vlm rollback`