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>
This commit is contained in:
windyboy
co-authored by
Claude Sonnet 4.5
Claude Sonnet 4.5
parent
0f0636bf19
commit
8a60aaf9a9
@@ -1,46 +1,88 @@
|
||||
# Repository Guidelines
|
||||
|
||||
## Project Structure & Module Organization
|
||||
- Core package lives in `src/vlm/`.
|
||||
- CLI entrypoint is `src/vlm/cli.py` (`vlm` console script). Shared CLI helpers live in `cli_helpers.py`. Command logic is in `commands/` (scan, parse, enrich, analyze, plan, execute, review_plan, report, quarantine_cmd, state_cmd, config_cmd).
|
||||
- Functional modules by concern: scanning (`scanner.py`), parsing (`parser.py`), enrichment (`enrichment.py`, `cache.py`, `providers/`), analysis/planning/execution (`analysis.py`, `planner.py`, `executor.py`), I/O helpers (`io.py`), utilities (`utils.py`), state/reporting/logging (`state.py`, `reports.py`, `logging_config.py`), config (`config.py`), models (`models.py`).
|
||||
- Tests live in `tests/` and mirror feature areas (e.g. `tests/test_scanner.py`, `tests/test_cli_state.py`, `tests/test_enrichment.py`).
|
||||
- Project metadata and tool config are in `pyproject.toml`.
|
||||
## Project Overview
|
||||
Video Library Manager (VLM) - Python CLI for managing personal video collections. Safety-first, human-in-the-loop approach. All operations reversible.
|
||||
|
||||
## Build, Test, and Development Commands
|
||||
- `uv pip install -e .` installs the package in editable mode.
|
||||
- `uv pip install -e ".[dev]"` installs dev dependencies (`pytest`, `hypothesis`, `pytest-cov`, `ruff`).
|
||||
- `uv run pytest -q` runs the full test suite.
|
||||
- `uv run pytest tests/test_logging.py` runs a targeted test file during iteration.
|
||||
- `uv run ruff check src tests` runs the linter (also in CI).
|
||||
- `vlm --help` verifies CLI startup and available commands.
|
||||
## Quick Start
|
||||
```bash
|
||||
uv pip install -e ".[dev]" # Install with dev deps
|
||||
uv run pytest -q # Run tests
|
||||
uv run vlm --help # Verify CLI
|
||||
```
|
||||
|
||||
## Coding Style & Naming Conventions
|
||||
- Use Python 3.10+ idioms, 4-space indentation, and PEP 8 naming.
|
||||
- Modules/functions/variables: `snake_case`; classes: `PascalCase`; constants: `UPPER_SNAKE_CASE`.
|
||||
- Keep modules focused on a single responsibility; prefer small pure helpers in domain modules.
|
||||
- Add type hints for public functions and non-trivial internal APIs.
|
||||
- Use absolute imports in `src/vlm/`: `from vlm.module import ...` (avoid new relative imports).
|
||||
- Ruff (`E`, `F`, `I`) is configured in `pyproject.toml`; CI runs `ruff check src tests`.
|
||||
## 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
|
||||
|
||||
## Testing Guidelines
|
||||
- Framework: `pytest`; property-based tests use `hypothesis`.
|
||||
- Naming (enforced in config): files `test_*.py`, functions `test_*`, classes `Test*`.
|
||||
- Add/extend tests with each behavior change, including CLI error paths and edge cases.
|
||||
- Prefer narrow unit tests for module logic plus targeted CLI integration tests via `CliRunner`.
|
||||
## 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
|
||||
|
||||
## Commit & Pull Request Guidelines
|
||||
- Current history is minimal; use clear, imperative commit subjects (example: `fix logging fallback for unwritable log dir`).
|
||||
- Keep commits focused; avoid mixing refactors and behavior changes unless tightly coupled.
|
||||
- PRs should include: summary, rationale, test evidence (`pytest` output), and any CLI-visible output changes.
|
||||
- Link related issues/tasks when applicable and call out config or migration impacts.
|
||||
## Key Concepts
|
||||
|
||||
## Security & Configuration Tips
|
||||
- Do not commit local paths, personal media metadata, or generated state/log artifacts.
|
||||
- Validate config changes against `vlm --help` and at least one end-to-end CLI flow before merging.
|
||||
### 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`.
|
||||
|
||||
## Documentation baseline
|
||||
- Updated to reflect release 0.2.0 baseline as of 2026-06-01.
|
||||
- Canonical release notes are tracked in `CHANGELOG.md`.
|
||||
- Default workflow artifacts: `artifacts/` (do not commit generated CSV/JSON).
|
||||
### 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`
|
||||
|
||||
Reference in New Issue
Block a user