From ff2660e083ec75110a8876183a6e3e157c757de6 Mon Sep 17 00:00:00 2001 From: Jarian Cottingham Date: Tue, 24 Feb 2026 03:21:19 -0600 Subject: [PATCH] Add AGENTS.md and install.sh script --- AGENTS.md | 297 +++++++++++++++++++++++++++++++++++++++++++++++++++++ install.sh | 18 ++++ 2 files changed, 315 insertions(+) create mode 100644 AGENTS.md create mode 100755 install.sh diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..ee6310d --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,297 @@ +# YouTube CLI Agent Guidelines + +## Project Overview + +This is a Python command-line interface (CLI) application for browsing and downloading YouTube videos using yt-dlp. The application provides both CLI and REST API interfaces, with support for search, pagination, playlist downloads, and network share integration. + +## System Requirements + +### Prerequisites (Install via system package manager) + +**macOS (using Homebrew):** +```bash +# Install Python 3 (includes pip) +brew install python + +# Install git +brew install git +``` + +**Ubuntu/Debian (using apt):** +```bash +# Install Python 3 and pip +sudo apt update +sudo apt install python3 python3-pip git + +# Optional: Install yt-dlp system-wide +sudo apt install yt-dlp +``` + +**Fedora/RHEL (using dnf/yum):** +```bash +# Install Python 3 and pip +sudo dnf install python3 python3-pip git +# or on older systems: +sudo yum install python3 python3-pip git + +# Optional: Install yt-dlp system-wide +sudo dnf install yt-dlp +``` + +### Python Dependencies (Install system-wide or in virtual environment) + +**Option 1: System-wide installation (no virtual environment needed)** +```bash +# Install Python packages system-wide +pip3 install --user yt-dlp rich requests flask==2.3.3 +``` + +**Option 2: Virtual environment (recommended for development)** +```bash +python3 -m venv venv +source venv/bin/activate +pip install -e . +# For API development: +pip install -r requirements-api.txt +``` + +**Option 3: Docker (isolation guaranteed)** +```bash +docker-compose up --build +``` + +### Installing yt-dlp + +**Using pip (recommended):** +```bash +pip3 install --user yt-dlp +``` + +**Using Homebrew (macOS):** +```bash +brew install yt-dlp +``` + +**Using apt (Ubuntu/Debian):** +```bash +sudo apt install yt-dlp +``` + +**Note:** The application requires yt-dlp version 2023.12.0 or later for full functionality. + +## Build & Deployment + +### Installation from Source (After installing prerequisites) +```bash +git clone +cd youtube-cli +pip3 install --user -e . +``` + +### Running the CLI Application +```bash +# Direct execution +youtube-cli "search query" + +# Using module syntax +python -m youtube_cli "search query" + +# Using run script +./run.sh "search query" +``` + +### Running the API Server +```bash +python app.py +``` +The API server runs on port 4096 by default. + +### Docker Deployment +```bash +docker-compose up --build +``` + +## Dependencies + +**Core dependencies (requirements.txt):** +- yt-dlp - YouTube video downloading +- rich - Terminal formatting and UI +- requests - HTTP requests for API calls + +**API dependencies (requirements-api.txt):** +- Flask==2.3.3 - REST API framework +- All core dependencies + +## Testing + +### Running Tests +```bash +# Run the API test script +python test_api.py + +# Run all tests with pytest (if configured) +pytest +``` + +### Running a Single Test +```bash +# Execute specific test file +python test_api.py + +# For pytest-based tests +pytest test_api.py::test_function_name +``` + +## Code Style Guidelines + +### Python Conventions +- **Python version:** 3.6+ +- **Style:** PEP 8 compliant +- **Line length:** 80 characters (strict) +- **Imports:** Grouped as: standard library, third-party, local +- **Type hints:** Optional but recommended for public APIs + +### Import Organization +```python +# 1. Standard library imports (alphabetical) +import argparse +import json +import os +import subprocess + +# 2. Third-party imports (alphabetical) +from rich.console import Console +from rich.table import Table + +# 3. Local imports +from youtube_cli.main import YouTubeCLI +``` + +### Naming Conventions +- **Classes:** PascalCase (e.g., `YouTubeCLI`, `VideoHandler`) +- **Functions/Variables:** snake_case (e.g., `search_videos`, `download_dir`) +- **Constants:** UPPERCASE (e.g., `MAX_VIDEOS_PER_PAGE`) +- **Private members:** Leading underscore (e.g., `_private_method`) + +### Error Handling +- Use try/except blocks for predictable error conditions +- Provide user-friendly error messages using Rich color tags +- Log detailed errors internally while showing simplified messages to users +- Use `console.print()` with colored output for all user-facing messages: + - `[red]` for errors + - `[green]` for success + - `[yellow]` for warnings + - `[blue]` for info + +### String Formatting +- Use f-strings for dynamic content +- Use Rich's inline markup for terminal colors: `[blue]text[/blue]` +- Escape special characters in user input to prevent injection + +## Architecture + +### Core Components + +**youtube_cli/main.py** +- Contains `YouTubeCLI` class with all main functionality +- Handles search, download, and archive operations +- Manages configuration and user interaction + +**youtube_cli/__main__.py** +- Entry point for CLI execution +- Calls `main()` from main.py + +**youtube_cli/__init__.py** +- Package initialization +- Version information + +**app.py** +- Flask-based REST API +- Provides JSON endpoints for search and download +- Implements MCP (Model Context Protocol) compliance + +### Data Flow +1. User input (CLI or API) +2. Request processing in `YouTubeCLI` methods +3. yt-dlp integration for YouTube operations +4. Configuration and archive management +5. Result delivery to user + +## Configuration + +**Configuration file location:** `~/.config/youtube_cli/config.json` + +**Key configuration options:** +- `download_dir`: Default download directory +- `default_locations`: List of category folders for downloads +- `max_videos_per_page`: Number of videos to display per page (default: 15) +- `yt_dlp_args`: Custom yt-dlp arguments (format, thumbnail, extractor args) +- `network_share_path`: Network share path for copying downloads +- `default_network_subfolder`: Default subfolder on network share + +### Archive System +- Stores downloaded videos in `~/.config/youtube_cli/downloaded_videos.json` +- Tracks videos by YouTube video ID +- Prevents duplicate downloads +- Supports pre-filling from existing downloads + +## API Endpoints + +| Endpoint | Method | Description | +|----------|--------|-------------| +| `/search` | GET | Search YouTube videos (requires `q` parameter) | +| `/download` | POST | Download video by URL (requires `url` field) | +| `/health` | GET | Health check endpoint | +| `/version` | GET | API version info | +| `/capabilities` | GET | MCP capabilities | +| `/openapi.json` | GET | OpenAPI specification | + +**API Port:** 4096 + +## Special Features + +### Short Video Detection +Videos with `/shorts/` in the URL are automatically detected and marked with "(short)" prefix in display. + +### Pagination +Search results display 15 videos per page. Users can navigate with 'n' for next page or 's' for new search. + +### Category Selection +Downloads require category selection from configured locations. Users can select from predefined categories or create custom folder names. + +### Network Share Integration +After download, videos can be automatically copied to configured network shares. + +### yt-dlp Integration +- Uses yt-dlp for all YouTube operations +- Supports custom format selection (default: 1080p) +- Handles JavaScript challenges with remote components +- Automatically checks for updates + +## Git Conventions + +- **Branch naming:** feature/branch-name or fix/branch-name +- **Commit messages:** Use present tense, imperative mood +- **Pull requests:** Include description of changes and testing steps + +## Development Notes + +### Adding New Features +1. Follow existing code structure and patterns +2. Use Rich for all terminal output +3. Implement proper error handling with user-friendly messages +4. Update documentation and README as needed +5. Test both CLI and API interfaces + +### Common Patterns +- Use `Path` objects for file operations +- Always validate user input +- Provide clear feedback during long operations +- Handle timeouts for external commands (yt-dlp, API calls) +- Use subprocess with proper timeout values (60s for search, 600s for download, 1200s for playlists) + +### Known Constraints +- Search results limited to 15 videos per page +- Download timeout: 10 minutes (600 seconds) +- Playlist download timeout: 20 minutes (1200 seconds) +- Network share path must exist and be writable \ No newline at end of file diff --git a/install.sh b/install.sh new file mode 100755 index 0000000..a6ba13f --- /dev/null +++ b/install.sh @@ -0,0 +1,18 @@ +#!/bin/bash +set -e + +echo "Installing YouTube CLI system-wide..." + +cd "$(dirname "$0")" + +# Install the package system-wide +pip3 install --user --break-system-packages -e . + +# Add Python user bin to PATH if not already present +if ! grep -q "Library/Python" ~/.zshrc 2>/dev/null; then + echo 'export PATH="$HOME/Library/Python/3.14/bin:$PATH"' >> ~/.zshrc + echo "Added Python user bin to ~/.zshrc" +fi + +echo "YouTube CLI installed successfully!" +echo "Run 'source ~/.zshrc' or restart your terminal to use youtube-cli" \ No newline at end of file