plex-playlist/docs/POE_TASK_REFERENCE.md

# Poe the Poet Task Reference

This project uses **Poe the Poet** as a unified task runner to simplify development workflows. All tasks are defined in `backend/pyproject.toml` and can be run from the project root.

## 🚀 Quick Start

```bash
# Install dependencies and set up development environment
poe setup

# See all available tasks
poe --help

# Interactive task selection
poe
```

## 📋 Essential Tasks

### Development Environment

```bash
poe dev              # Start development environment (Docker Compose)
poe dev-down         # Stop development environment
poe dev-logs         # Follow development logs
poe dev-restart      # Restart development environment
```

### Code Quality (Unified Backend + Frontend)

```bash
poe format           # Format all code (Python + TypeScript)
poe lint             # Lint all code (Python + TypeScript)
poe type-check       # Type check all code (Python + TypeScript)
```

### Testing

```bash
poe test-unit        # Run all unit tests (backend + frontend)
poe test-all         # Run all tests including integration
poe test-full        # Run all tests with coverage + E2E
poe test-e2e         # Run end-to-end tests only
```

### CI/CD Pipeline

```bash
poe ci-quick         # Fast quality checks (format, lint, type-check)
poe ci-full          # Complete CI pipeline simulation
poe quality-gate     # All quality checks (like CI)
```

### Docker Images

```bash
poe build-cicd       # Build both base and complete CI/CD images
poe build-cicd-base  # Build only base image (cached dependencies)
poe build-cicd-complete  # Build only complete image (fast)
```

## 🏃‍♂️ Performance Tasks (Parallel Execution)

```bash
poe lint-parallel         # Run linting in parallel for speed
poe type-check-parallel   # Run type checking in parallel
poe test-parallel         # Run tests in parallel
```

## 🧠 Smart Tasks (Conditional Execution)

```bash
poe test-if-changed       # Only test if code changed
poe build-if-dockerfile-changed  # Only build if Dockerfiles changed
```

## 🛠 Utility Tasks

```bash
poe audit-backend   # Run backend pip-audit dependency audit
poe audit-frontend  # Run frontend Yarn npm audit
poe deps-check      # Run dependency checks across backend and frontend
poe deps-install     # Install all dependencies (backend + frontend)
poe deps-update      # Update all dependencies
poe clean            # Clean build artifacts and caches
poe reset            # Complete reset (clean + reinstall)
```

## 🔧 Individual Component Tasks

### Backend Only

```bash
poe format-backend       # Format Python code only
poe lint-backend         # Lint Python code only
poe type-check-backend   # Type check Python only
poe test-backend         # Run backend tests only
poe test-backend-cov     # Backend tests with coverage
```

### Frontend Only

```bash
poe format-frontend      # Format TypeScript code only
poe lint-frontend        # Lint TypeScript code only
poe type-check-frontend  # Type check TypeScript only
poe test-frontend        # Run frontend tests only
poe test-frontend-cov    # Frontend tests with coverage
```

## 📚 Documentation Tasks

```bash
poe docs-backend     # Run docstring tests
poe docs-check       # Check docstring quality
```

## 🎣 Pre-commit Integration

```bash
poe pre-commit-install   # Install pre-commit hooks
poe pre-commit-run       # Run all pre-commit hooks
poe pre-commit-update    # Update hook versions
```

## 💡 Tips & Tricks

### Task Discovery

```bash
poe --help           # List all tasks with descriptions
poe <task> --help    # Get help for specific task
poe                  # Interactive task picker
```

### Chaining Tasks

```bash
# Run multiple tasks in sequence
poe format lint type-check test-unit

# Custom workflows
poe clean deps-install ci-quick
```

### Environment Context

- All tasks run from project root
- Backend tasks automatically use `uv run` in correct environment
- Frontend tasks automatically use `yarn` in correct directory
- Docker tasks use the optimized multi-stage CI/CD setup

### Performance Tips

- Use parallel tasks (`*-parallel`) for faster feedback
- Use conditional tasks (`*-if-changed`) to save time
- `poe setup` configures everything for new developers
- `poe quality-gate` runs full CI checks locally

## 🔄 Migration from Manual Commands

### Before (Manual)

```bash
cd backend && uv run ruff format .
cd frontend && yarn prettier --write src/
cd backend && uv run pytest
cd frontend && yarn test
./scripts/build-cicd-local.sh
```

### After (Poe)

```bash
poe format
poe test-unit
poe build-cicd
```

## 🏗 Integration with Existing Workflows

- **Pre-commit hooks**: Still work as before, Poe complements them
- **CI/CD pipeline**: Uses same tools, Poe provides local simulation
- **Docker development**: `poe dev` replaces manual docker-compose commands
- **Scripts**: Existing scripts still work, Poe provides unified interface

## 🎯 Next Steps

1. **Try it out**: `poe setup` to get started
2. **Explore tasks**: `poe --help` to see all options
3. **Customize**: Add project-specific tasks to `backend/pyproject.toml`
4. **Share**: Team members can use same unified interface

This unified task system makes development faster, more consistent, and easier for new team members to learn!