Aniworld/docs/instructions.md

# Aniworld Web Application Development Instructions

This document provides detailed tasks for AI agents to implement a modern web application for the Aniworld anime download manager. All tasks should follow the coding guidelines specified in the project's copilot instructions.

## Project Overview

The goal is to create a FastAPI-based web application that provides a modern interface for the existing Aniworld anime download functionality. The core anime logic should remain in `SeriesApp.py` while the web layer provides REST API endpoints and a responsive UI.

## Architecture Principles

-   **Single Responsibility**: Each file/class has one clear purpose
-   **Dependency Injection**: Use FastAPI's dependency system
-   **Clean Separation**: Web layer calls core logic, never the reverse
-   **File Size Limit**: Maximum 500 lines per file
-   **Type Hints**: Use comprehensive type annotations
-   **Error Handling**: Proper exception handling and logging

## Additional Implementation Guidelines

### Code Style and Standards

-   **Type Hints**: Use comprehensive type annotations throughout all modules
-   **Docstrings**: Follow PEP 257 for function and class documentation
-   **Error Handling**: Implement custom exception classes with meaningful messages
-   **Logging**: Use structured logging with appropriate log levels
-   **Security**: Validate all inputs and sanitize outputs
-   **Performance**: Use async/await patterns for I/O operations

## 📞 Escalation

If you encounter:

-   Architecture issues requiring design decisions
-   Tests that conflict with documented requirements
-   Breaking changes needed
-   Unclear requirements or expectations

**Document the issue and escalate rather than guessing.**

---

## 📚 Helpful Commands

```bash
# Run all tests
conda run -n AniWorld python -m pytest tests/ -v --tb=short

# Run specific test file
conda run -n AniWorld python -m pytest tests/unit/test_websocket_service.py -v

# Run specific test class
conda run -n AniWorld python -m pytest tests/unit/test_websocket_service.py::TestWebSocketService -v

# Run specific test
conda run -n AniWorld python -m pytest tests/unit/test_websocket_service.py::TestWebSocketService::test_broadcast_download_progress -v

# Run with extra verbosity
conda run -n AniWorld python -m pytest tests/ -vv

# Run with full traceback
conda run -n AniWorld python -m pytest tests/ -v --tb=long

# Run and stop at first failure
conda run -n AniWorld python -m pytest tests/ -v -x

# Run tests matching pattern
conda run -n AniWorld python -m pytest tests/ -v -k "auth"

# Show all print statements
conda run -n AniWorld python -m pytest tests/ -v -s

#Run app
conda run -n AniWorld python -m uvicorn src.server.fastapi_app:app --host 127.0.0.1 --port 8000 --reload
```

---

## Implementation Notes

1. **Incremental Development**: Implement features incrementally, testing each component thoroughly before moving to the next
2. **Code Review**: Review all generated code for adherence to project standards
3. **Documentation**: Document all public APIs and complex logic
4. **Testing**: Maintain test coverage above 80% for all new code
5. **Performance**: Profile and optimize critical paths, especially download and streaming operations
6. **Security**: Regular security audits and dependency updates
7. **Monitoring**: Implement comprehensive monitoring and alerting
8. **Maintenance**: Plan for regular maintenance and updates

## Task Completion Checklist

For each task completed:

-   [ ] Implementation follows coding standards
-   [ ] Unit tests written and passing
-   [ ] Integration tests passing
-   [ ] Documentation updated
-   [ ] Error handling implemented
-   [ ] Logging added
-   [ ] Security considerations addressed
-   [ ] Performance validated
-   [ ] Code reviewed
-   [ ] Task marked as complete in instructions.md
-   [ ] Infrastructure.md updated and other docs
-   [ ] Changes committed to git; keep your messages in git short and clear
-   [ ] Take the next task

---

### Prerequisites

1. Server is running: `conda run -n AniWorld python -m uvicorn src.server.fastapi_app:app --host 127.0.0.1 --port 8000 --reload`
2. Password: `Hallo123!`
3. Login via browser at `http://127.0.0.1:8000/login`

### Notes

-   This is a simplification that removes complexity while maintaining core functionality
-   Improves user experience with explicit manual control
-   Easier to understand, test, and maintain
-   Good foundation for future enhancements if needed

---

## Task: Enhanced Anime Add Flow ✅ COMPLETED

### Overview

Enhance the anime addition workflow to automatically persist anime to the database, scan for missing episodes immediately, and create folders using the anime display name instead of the internal key.

### Requirements

1. **After anime add → Save to database**: Ensure the anime is persisted to the database via `AnimeDBService.create_series()` immediately after validation
2. **After anime add → Scan for missing episodes**: Trigger a targeted episode scan for only the newly added anime (not the entire library)
3. **After anime add → Create folder with anime name**: Use the anime display name (sanitized) for the folder, not the anime key

### Implementation Steps

#### Step 1: Examine Current Implementation

1. Open and read `src/server/routes/anime_routes.py` - find the `add_series` endpoint
2. Open and read `src/core/SerieScanner.py` - understand how scanning works
3. Open and read `src/core/entities/Serie.py` and `src/core/entities/SerieList.py` - understand folder handling
4. Open and read `src/database/services/anime_db_service.py` - understand database operations
5. Open and read `src/core/providers/AniWorldProvider.py` - understand how folders are created

#### Step 2: Create Utility Function for Folder Name Sanitization

1. Create or update utility module at `src/utils/filesystem.py`
2. Implement `sanitize_folder_name(name: str) -> str` function that:
    - Removes/replaces characters invalid for filesystems: `< > : " / \ | ? *`
    - Trims leading/trailing whitespace and dots
    - Handles edge cases (empty string, only invalid chars)
    - Preserves Unicode characters (for Japanese titles, etc.)

#### Step 3: Update Serie Entity

1. Open `src/core/entities/Serie.py`
2. Add a `folder` property that returns sanitized display name instead of key
3. Ensure backward compatibility with existing series

#### Step 4: Update SerieList to Use Display Name for Folders

1. Open `src/core/entities/SerieList.py`
2. In the `add()` method, use `serie.folder` (display name) instead of `serie.key` when creating directories
3. Ensure the folder path is correctly stored in the Serie object

#### Step 5: Add Targeted Episode Scan Method to SerieScanner

1. Open `src/core/SerieScanner.py`
2. Add new method `scan_single_series(self, key: str) -> List[Episode]`:
    - Fetches the specific anime from database/SerieList by key
    - Calls the provider to get available episodes
    - Compares with local files to find missing episodes
    - Returns list of missing episodes
    - Does NOT trigger a full library rescan

#### Step 6: Update add_series Endpoint

1. Open `src/server/routes/anime_routes.py`
2. Modify the `add_series` endpoint to:
    - **Step A**: Validate the request (existing)
    - **Step B**: Create Serie object with sanitized folder name
    - **Step C**: Save to database via `AnimeDBService.create_series()`
    - **Step D**: Add to SerieList (which creates the folder)
    - **Step E**: Call `SerieScanner.scan_single_series(key)` for targeted scan
    - **Step F**: Return response including:
        - Success status
        - Created folder path
        - List of missing episodes found (if any)

#### Step 7: Update Provider Folder Handling

1. Open `src/core/providers/AniWorldProvider.py`
2. Ensure download operations use `serie.folder` for filesystem paths
3. If `EnhancedProvider.py` exists, update it similarly

### Acceptance Criteria

-   [x] When adding a new anime, it is immediately saved to the database
-   [x] When adding a new anime, only that anime is scanned for missing episodes (not full library)
-   [x] Folder is created using the sanitized display name (e.g., "Attack on Titan" not "attack-on-titan")
-   [x] Special characters in anime names are properly handled (`:`, `?`, etc.)
-   [x] Existing anime entries continue to work (backward compatibility)
-   [x] API response includes the created folder path and missing episodes count
-   [x] Unit tests cover the new functionality
-   [x] No regressions in existing tests

### Implementation Summary (Completed)

**Files Created/Modified:**
- `src/server/utils/filesystem.py` - New file with `sanitize_folder_name()`, `is_safe_path()`, `create_safe_folder()`
- `src/core/entities/series.py` - Added `sanitized_folder` property
- `src/core/entities/SerieList.py` - Updated `add()` to use sanitized folder names
- `src/core/SerieScanner.py` - Added `scan_single_series()` method
- `src/server/api/anime.py` - Enhanced `add_series` endpoint with full flow

**Tests Added:**
- `tests/unit/test_filesystem_utils.py` - 43 tests for filesystem utilities
- `tests/unit/test_serie_class.py` - 6 tests for `sanitized_folder` property
- `tests/unit/test_serie_scanner.py` - 9 tests for `scan_single_series()`
- `tests/api/test_anime_endpoints.py` - 6 integration tests for enhanced add flow

**All 97 related tests passing. No regressions in existing 848 unit tests and 60 API tests.**

### Testing Requirements

1. **Unit Tests**:

    - Test `sanitize_folder_name()` with various inputs (special chars, Unicode, edge cases)
    - Test `Serie.folder` property returns sanitized name
    - Test `SerieScanner.scan_single_series()` only scans the specified anime
    - Test database persistence on anime add

2. **Integration Tests**:
    - Test full add flow: request → database → folder creation → scan
    - Test that folder is created with correct name
    - Test API response contains expected fields

### Error Handling

-   If database save fails, return appropriate error and don't create folder
-   If folder creation fails (permissions, disk full), return error and rollback database entry
-   If scan fails, still return success for add but indicate scan failure in response
-   Log all operations with appropriate log levels

### Security Considerations

-   Sanitize folder names to prevent path traversal attacks
-   Validate anime name length to prevent filesystem issues
-   Ensure folder is created within the configured library path only

---