Stop tracking personal workflow artifacts at repo root, add CI and MIT
license, align README and agent skills with artifacts/ defaults, and
enable Ruff in dev/CI so releases are verifiable without local-only runs.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Extract review-plan, report, quarantine, state, and config handlers into
commands/ with shared cli_helpers; remove unused exceptions and duplicate
plan summary wrappers. Archive superseded review markdown, sync docs to
517-test baseline, and fix empty series titles when only a quality tag remains.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Make review-plan easier to act on: Chinese risk labels, relative paths,
verdict/next-step footer, optional identity/analysis enrichment, grouping,
spot-check sampling, and structure preview. Extend the TUI with filters,
duplicate-group reject, and quality context. Persist review_context on
plan operations and add --require-review for confirmed execute.
Co-authored-by: Cursor <cursoragent@cursor.com>
Adds vlm_schema_version field to all data file formats for schema
evolution and migration tracking. Task #1 already added versioning
to identities.json; this completes the remaining files.
Changes to scanner.py:
- Add "# vlm_schema_version: 1.0" as first comment line in inventory.csv
Changes to commands/analyze.py:
- Add "vlm_schema_version": "1.0" to analysis.json root
Changes to planner.py:
- Add "vlm_schema_version": "1.0" to plan.json root
Changes to executor.py:
- Add "vlm_schema_version": "1.0" to rollback log JSON
Schema versions:
- inventory.csv: 1.0 (in comment header)
- identities.json: 1.0 or 2.0 (set by parse command)
- analysis.json: 1.0
- plan.json: 1.0
- rollback_log.json: 1.0
Future migrations:
- Version field allows detecting old formats
- Can implement auto-migration logic
- Can warn users about version mismatches
- Enables schema evolution without breaking changes
Testing:
- All 449 tests pass
- No test changes needed (backward compatible)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Implements centralized path canonicalization to ensure symlinks and paths
with . or .. segments are resolved to their canonical form, preventing
false duplicate detection.
Changes to utils.py:
- Add canonical_path() function using Path.resolve()
- Add canonical_path_str() for dictionary key usage
Changes to models.py:
- Add __post_init__ to VideoFile to auto-canonicalize paths
- All VideoFile instances now have canonical paths automatically
Impact:
- Path-based dictionary lookups now work correctly with symlinks
- io.py: path_to_inventory dictionary uses canonical keys
- planner.py: path_to_index dictionary uses canonical keys
- analysis.py: Duplicate detection uses canonical paths
- No false duplicates from symlinks or relative paths
Testing:
- Added comprehensive tests for canonical_path functions
- Tests verify symlink resolution, absolute path conversion, .. removal
- All 449 tests pass (added 10 new tests)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Implements atomic quarantine/restore operations using two-phase commit
pattern to prevent orphaned files when manifest updates fail.
Changes to models.py:
- Add status field to QuarantineEntry ("pending" | "committed")
- Default to "committed" for backward compatibility
Changes to quarantine.py:
- Rewrite quarantine_file() with three phases:
1. Write pending manifest entry BEFORE moving file
2. Move file to quarantine
3. Mark manifest entry as committed
- Rewrite restore_from_quarantine() with same pattern
- Add _recover_pending_entries() for auto-recovery on manifest load
- Update _load_manifest() and _save_manifest() to handle status field
Changes to executor.py:
- Add special handling for quarantine rollback using QuarantineManager
- Fix bug where executor didn't preserve quarantine destination_path
- Return QuarantineManager result directly (includes actual quarantine path)
Testing:
- Fixed pre-existing test_rollback_quarantine_operation
- All 439 tests now pass (was 438 with 1 failure)
Atomicity guarantees:
- If manifest write fails → operation fails, no file moved
- If file move fails → rollback removes pending manifest entry
- If commit fails → auto-recovery fixes on next load
- No orphaned files possible
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Implements identities.json v2 schema with embedded video metadata to fix
duplicate resolution by quality, which previously failed due to VideoFile
objects being reconstructed with hardcoded defaults (size_bytes=0,
resolution=None, codec=None).
Changes:
- Add --inventory flag to vlm parse command to embed video metadata
- Update _video_file_from_record() to extract embedded metadata if present
- Add vlm_schema_version field to identities.json (v1.0 or v2.0)
- Maintain backward compatibility with v1 files (no metadata)
Schema v2 format:
- Embeds video_metadata object in each record (movies/series)
- Contains: size_bytes, modified_timestamp, resolution, codec,
duration_seconds, bitrate_kbps
- Enables accurate quality comparison during duplicate analysis
Testing:
- Added comprehensive unit tests for io.py functions
- Added CLI integration tests for parse command
- Added end-to-end tests for duplicate quality comparison
- All 437 existing tests still pass (1 pre-existing failure in executor)
Documentation:
- Updated README.md with --inventory usage examples
- Updated CLAUDE.md with schema versioning details
- Added workflow examples showing metadata embedding
This fix resolves the critical P0 issue where duplicate resolution by_quality
strategy failed completely due to missing video metadata in reconstructed
VideoFile objects.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
- Updated `duplicate_resolve.py` to introduce a new strategy for keeping files based on quality, considering resolution, source, codec, and size.
- Enhanced `planner.py` to utilize the new quality-based strategy during plan generation, updating quarantine reasons accordingly.
- Modified `README.md` to document the new `plan.duplicate_keep` options, including `by_quality`, and provided detailed descriptions of each strategy.
- Added unit tests in `test_duplicate_resolve.py` to validate the new quality-based resolution logic.
- Updated `analysis.json` and `plan.json` with new timestamps and IDs to reflect recent changes.
These updates improve the Video Library Manager's ability to handle duplicate files more effectively, ensuring users retain the highest quality versions.
- Updated `analysis.json` with a new generation timestamp.
- Modified `plan.json` to include a new plan ID and created timestamp, and changed operation types from "no-op" to "quarantine" for specific files needing manual review.
- Enhanced the README.md to document the new `--analysis` option for generating execution plans, which now includes a human-readable summary and duplicate handling strategies.
- Introduced a new `duplicate_resolve.py` module to manage duplicate file resolution strategies.
- Improved the execution engine to support quarantine operations and added rollback functionality for quarantined files.
These changes improve the functionality of the Video Library Manager by providing better duplicate management and clearer reporting capabilities.
- Updated AGENTS.md to reflect changes in CLI commands and module organization, including the addition of an enrichment step and new functional modules.
- Introduced analysis.json, identities.json, inventory.csv, and plan.json to support enriched metadata and execution planning.
- Added CODE_IMPROVEMENTS.md to document identified code issues and proposed solutions for future enhancements.
- Updated README.md to include new enrichment features and configuration options.
- Removed unused dependency on ffmpeg-python from pyproject.toml.
These changes improve the overall functionality and maintainability of the Video Library Manager project.
Allow users to configure multiple directory names per category (movie/series/anime) to support variations like "movies", "tv", "films". This enables proper categorization of files in directories that don't match the hardcoded singular forms, solving the issue where 635 files in "/mnt/Downloads/movies/" were incorrectly categorized as "other".
Configuration example:
categories:
movie: [movie, movies, films]
series: [series, tv, shows]
anime: [anime]
Changes include comprehensive validation, backward-compatible defaults, case-insensitive matching, and full test coverage (395 tests passing).
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
- Add AGENTS.md with comprehensive repository guidelines covering project structure, build/test commands, coding style, testing practices, and commit conventions
- Add REVIEW_REPORT.md documenting code review findings including 4 actionable issues: logging permission errors, incorrect test imports, timezone conversion bugs, and dead error counter code
- Include detailed recommendations for fix prioritization and test evidence from pytest runs
- Provide reference documentation for future development and maintenance workflows
