windyboyandClaude Sonnet 4.5
8a60aaf9a9
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>
89 lines
3.6 KiB
Markdown
89 lines
3.6 KiB
Markdown
# 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
|
|
```bash
|
|
uv pip install -e ".[dev]" # Install with dev deps
|
|
uv run pytest -q # Run tests
|
|
uv run vlm --help # Verify CLI
|
|
```
|
|
|
|
## Core Workflow
|
|
1. `vlm scan` → discover files → `artifacts/inventory.csv`
|
|
2. `vlm parse` → extract identities → `artifacts/identities.json`
|
|
3. `vlm enrich` → (optional) add TMDB metadata
|
|
4. `vlm analyze` → detect gaps/duplicates → `artifacts/analysis.json`
|
|
5. `vlm plan` → generate execution plan → `artifacts/plan.json`
|
|
6. `vlm review-plan` → preview high-risk operations
|
|
7. `vlm execute` → dry-run by default, `--confirm` to execute
|
|
8. `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
|
|
```bash
|
|
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`
|