Files

T

windyboyandClaude Sonnet 4.5 8a60aaf9a9 docs: consolidate CLAUDE.md into AGENTS.md and simplify

Merge detailed content from CLAUDE.md into AGENTS.md, then condense
to essential information. Removes Claude-specific documentation in
favor of tool-agnostic guidelines.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

2026-09-25 14:05:44 +08:00

3.6 KiB

Raw Blame History

Repository Guidelines

Project Overview

Video Library Manager (VLM) - Python CLI for managing personal video collections. Safety-first, human-in-the-loop approach. All operations reversible.

Quick Start

uv pip install -e ".[dev]"     # Install with dev deps
uv run pytest -q               # Run tests
uv run vlm --help              # Verify CLI

Core Workflow

vlm scan → discover files → artifacts/inventory.csv
vlm parse → extract identities → artifacts/identities.json
vlm enrich → (optional) add TMDB metadata
vlm analyze → detect gaps/duplicates → artifacts/analysis.json
vlm plan → generate execution plan → artifacts/plan.json
vlm review-plan → preview high-risk operations
vlm execute → dry-run by default, --confirm to execute
vlm rollback → undo executed operations

Project Structure

src/vlm/cli.py - CLI entrypoint
src/vlm/commands/ - Command implementations (scan, parse, enrich, analyze, plan, execute, review_plan, report, quarantine_cmd, state_cmd, config_cmd)
src/vlm/scanner.py - File discovery + ffprobe metadata
src/vlm/parser.py - Filename parsing (movies: title+year, series: SxxExx)
src/vlm/enrichment.py - TMDB enrichment pipeline
src/vlm/planner.py - Execution plan generation
src/vlm/executor.py - File operations with rollback
src/vlm/models.py - Data structures (VideoFile, MovieIdentity, SeriesIdentity, etc.)
tests/ - Test suite mirroring source modules

Key Concepts

Safety Protocol

NEVER delete files permanently - use quarantine
All operations create rollback logs with --confirm
Default mode is dry-run

File Categorization

Based on top-level directory matching categories config (case-insensitive). Default: movie, series, anime.

Schema Versions

v1 (default): Lightweight, no embedded metadata
v2 (with --inventory): Includes video metadata for quality-aware duplicate resolution

Parsing Patterns (Hardcoded)

Movies: {title} ({year}) or {title}.{year}
Series: S{season:02d}E{episode:02d} or {season}x{episode}

Development Commands

uv run pytest                           # All tests
uv run pytest tests/test_scanner.py     # Specific file
uv run ruff check src tests             # Lint
uv run vlm scan                         # Discover files
uv run vlm parse --inventory artifacts/inventory.csv  # Parse with metadata
uv run vlm plan --analysis artifacts/analysis.json    # Plan with duplicates
uv run vlm review-plan --tui            # Interactive review (requires [tui])

Code Style

Python 3.10+, 4-space indent, PEP 8
snake_case functions/vars, PascalCase classes, UPPER_SNAKE_CASE constants
Type hints for public APIs
Absolute imports: from vlm.module import ...
Ruff (E, F, I) enforced in CI

Testing

pytest + hypothesis for property-based tests
Naming: test_*.py, test_*(), Test*
Add tests with behavior changes
Prefer unit tests + targeted CLI integration via CliRunner

Commit Guidelines

Imperative subjects: fix logging fallback for unwritable log dir
Keep commits focused (no mixed refactors + behavior changes)
Include: Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
PRs: summary, rationale, test evidence, CLI output changes

Important Notes

Anime: discovered but not parsed in v1
State tracking: optional, persisted to ~/.vlm/state.json
Quarantine: only movie/series (not anime/other)
Timestamps: UTC ISO 8601 format
Logging: ~/.vlm/vlm.log, falls back to console if unwritable
Config: ~/.vlm/config.yaml

3.6 KiB Raw Blame History