diff --git a/.gitignore b/.gitignore index 08263483..eadc9849 100644 --- a/.gitignore +++ b/.gitignore @@ -19,4 +19,5 @@ tags env/ .idea/ venv/ -test.py \ No newline at end of file +test.py +uv.lock diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..a96d1883 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,47 @@ +# Repository Guidelines + +## Project structure & module organization +This repository is a Python CLI application packaged as `yewtube`. +Core code lives in `mps_youtube/`, with command handlers in +`mps_youtube/commands/`, player backends in `mps_youtube/players/`, and +list rendering helpers in `mps_youtube/listview/`. Project configuration is in +`pyproject.toml`, dependency locking is in `uv.lock`, and packaging metadata is +in `yewtube.egg-info/`. + +## Build, test, and development commands +Use `uv` for local workflows. + +- `uv sync` installs runtime and dev dependencies from `pyproject.toml` and + `uv.lock`. +- `uv run yt` runs the CLI entry point (`yt = mps_youtube.main:main`). +- `uv run ruff check .` runs lint checks. +- `uv run ruff check . --fix` auto-fixes safe lint issues. +- `uv run python -m mps_youtube.main` runs the app directly during debugging. + +## Coding style & naming conventions +Follow the existing Python style in `mps_youtube/`. + +- Use 4-space indentation and keep lines readable around the configured + 80-character target. +- Keep module and function names `snake_case`, classes `PascalCase`, and + constants `UPPER_SNAKE_CASE`. +- Prefer small, focused command modules under `mps_youtube/commands/`. +- Run `ruff` before committing; lint rules are configured in + `pyproject.toml`. + +## Testing guidelines +There is currently no dedicated automated test suite in this repository. + +- Add new tests under a top-level `tests/` directory using `test_*.py` naming. +- For behavior changes, include at least one automated test or document manual + verification steps in your pull request. +- Minimum manual check: run `uv run yt` and verify the changed command path. + +## Commit & pull request guidelines +The current Git history uses short, imperative commit messages +(for example, `Capture current state for review`, `initial commit`). + +- Write concise, imperative commits focused on one logical change. +- In pull requests, include: what changed, why, and how you validated it. +- Link related issues when available and include terminal output or screenshots + for user-visible CLI behavior changes. diff --git a/GEMINI.md b/GEMINI.md new file mode 100644 index 00000000..f861a5e1 --- /dev/null +++ b/GEMINI.md @@ -0,0 +1,46 @@ +# yewtube (yt) - Terminal YouTube Player + +This directory is a specialized workspace for **yewtube** (a fork of `mps-youtube`), a terminal-based YouTube player and downloader that does not require a YouTube API key. + +## Project Overview + +- **Purpose**: Search, stream, and download YouTube content directly from the command line. +- **Core Technologies**: Python 3.x, `yt-dlp`, `requests`, `pafy`, and `youtube-search-python`. +- **Playback Engines**: Supports `mpv`, `mplayer`, and `VLC`. +- **Architecture**: A terminal-based interactive CLI that interfaces with YouTube's web interface (via `pafy` and `yt-dlp`) to bypass API requirements. + +## Environment & Tools + +The project is managed via a `uv` virtual environment located in `.venv/`. + +### Key Executables +- `yt`: The main interactive terminal interface. +- `yt-dlp`: The underlying engine used for downloading and extracting media information. + +## Usage Guide + +To start the interface, run: +```bash +./.venv/bin/yt +``` + +### Common Commands (Internal to `yt`) +- `/ `: Search for videos. +- `// `: Search for playlists. +- `1-5`: Play videos 1 through 5. +- `d 1`: Download video 1. +- `set