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
README.md
+14 -5
View File
@@ -2,11 +2,14 @@
## Documentation Status
- Last synchronized: **2026-04-02**
- Last synchronized: **2026-04-07**
- Validation baseline: **`pytest -q` → 507 passed**
- Human-in-the-loop workflow includes `vlm apply-review` for syncing manual plan edits from CSV back into `plan.json`.
- Scanner now detects `ffprobe` availability and degrades gracefully.
- JSON artifacts (`identities.json`, `analysis.json`, `plan.json`) are schema-validated on load/save.
- Scanner now detects `ffprobe` availability, degrades gracefully, and treats partial `find` output as a warning-backed partial result.
- JSON artifacts (`identities.json`, `analysis.json`, `plan.json`) are schema-validated on load/save, and plan loading now crosses a typed `ExecutionPlan` boundary.
- Plan generation separates logical intent from environment-derived validation snapshots, improving reproducibility.
- `vlm review-plan --tui` remains an optional Textual dependency; the default CLI path does not require Textual.
- Execution rejects move/rename plans whose source or destination escapes `library_root`.
A Python-based CLI tool for managing personal video collections with a safety-first, human-in-the-loop approach.
@@ -40,6 +43,8 @@ uv pip install -e ".[dev]"
uv pip install -e ".[tui]"
```
The standard CLI remains fully usable without Textual; the dependency is imported only when `vlm review-plan --tui` is requested.
## Quick Start
### 1. Initialize Configuration
@@ -69,6 +74,7 @@ This creates `artifacts/inventory.csv` with all discovered files and their metad
**What happens:**
- Discovers video files using the system `find` command
- If `find` exits non-zero after emitting paths, VLM keeps the partial results and logs a warning; if no paths are emitted, discovery returns an empty deterministic result
- Extracts file metadata (size, modification time)
- Categorizes files based on directory structure (movie/series/anime/other)
- Extracts video metadata using ffprobe (if available)
@@ -157,6 +163,7 @@ This creates `artifacts/plan.json` with:
Safety guards in planning:
- Titles used in path templates are sanitized (path separators/control chars/`..` stripped)
- Any destination outside `library_root` is rejected as `no-op`
- Duplicate resolution with `--analysis` is deterministic: unresolved `by_quality` groups are converted into explicit manual-review `no-op` operations instead of silently keeping the first file
Duplicate keep strategy is configurable in `~/.vlm/config.yaml` under `plan.duplicate_keep`:
- `by_quality` - Prefer highest quality (resolution > source > codec > file size). Best for automatic duplicate resolution.
@@ -165,9 +172,10 @@ Duplicate keep strategy is configurable in `~/.vlm/config.yaml` under `plan.dupl
- `first_seen` - Keep the first file in each duplicate group.
- `manual` - Do not generate quarantine operations; duplicates are listed in analysis only.
**Review the plan** in one of three ways:
**Review the plan** in one of four ways:
- Open `artifacts/plan.json` in your editor
- Run `vlm review-plan` to get a terminal preview (summary + high-risk operation preview)
- Run `vlm review-plan --tui` for the optional full-screen Textual review UI
- Run `vlm execute` to see the same plan summary in dry-run mode
You can still edit `plan.json` directly when needed.
@@ -189,7 +197,8 @@ vlm execute --confirm
**Important**: This creates a rollback log in `~/.vlm/rollback/` for reverting changes.
Execution safeguards:
- Even if a manually edited `artifacts/plan.json` contains an unsafe destination, execution rejects paths outside `library_root`
- Even if a manually edited `artifacts/plan.json` contains an unsafe move/rename source or destination, execution rejects paths outside `library_root`
- Unsupported quarantine operations are reported as failed results without aborting later operations in the same run
- Summary counters treat conflict skips separately from real failures (`failed`/`skipped` are mutually exclusive)
### 8. Rollback (If Needed)