ActivityPub-federated video streaming platform using P2P directly in your web browser
Add copilot instructions
Chocobozzzfcca9b72d344
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.mdnew file mode 100644index 0000000000..a219e7b442--- /dev/null+++ b/.github/copilot-instructions.md@@ -0,0 +1,222 @@+# PeerTube Copilot Instructions++## Repository Overview++PeerTube is an open-source, ActivityPub-federated video streaming platform using P2P technology directly in web browsers. It's developed by Framasoft and provides a decentralized alternative to centralized video platforms like YouTube.++**Repository Stats:**+- **Size**: Large monorepo (~350MB, ~15k files)+- **Type**: Full-stack web application+- **Languages**: TypeScript (backend), Angular (frontend), Shell scripts+- **Target Runtime**: Node.js >=20.x, PostgreSQL >=10.x, Redis >=6.x+- **Package Manager**: Yarn 1.x (NOT >=2.x)+- **Architecture**: Express.js API server + Angular SPA client + P2P video delivery++## Critical: Client Directory Exclusion++**π« ALWAYS IGNORE `client/` directory** - it contains a separate Angular frontend project with its own build system, dependencies, and development workflow. Focus only on the server-side backend code.++## Build & Development Commands++### Prerequisites (Required)+1. **Dependencies**: Node.js >=20.x, Yarn 1.x, PostgreSQL >=10.x, Redis >=6.x, FFmpeg >=4.3, Python >=3.8+2. **PostgreSQL Setup**:+ ```bash+ sudo -u postgres createuser -P peertube+ sudo -u postgres createdb -O peertube peertube_dev+ sudo -u postgres psql -c "CREATE EXTENSION pg_trgm;" peertube_dev+ sudo -u postgres psql -c "CREATE EXTENSION unaccent;" peertube_dev+ ```+3. **Services**: Start PostgreSQL and Redis before development++### Installation & Build (Execute in Order)+```bash+# 1. ALWAYS install dependencies first (takes ~2-3 minutes)+yarn install --frozen-lockfile++# 2. Build server (required for most operations, takes ~3-5 minutes)+npm run build:server++# 3. Optional: Build full application (takes ~10-15 minutes)+npm run build+```++**β οΈ Critical Notes:**+- Always run `yarn install --frozen-lockfile` before any build operation+- Server build is prerequisite for testing and development+- Never use `npm install` - always use `yarn`+- Build failures often indicate missing PostgreSQL extensions or wrong Node.js version++### Development Commands+```bash+# Server-only development (recommended for backend work)+npm run dev:server # Starts server on localhost:9000 with hot reload++# Full stack development (NOT recommended if only working on server)+npm run dev # Starts both server (9000) and client (3000)++# Development credentials:+# Username: root+# Password: test+```++### Testing Commands (Execute in Order)+```bash+# 1. Prepare test environment (required before first test run)+sudo -u postgres createuser $(whoami) --createdb --superuser+npm run clean:server:test++# 2. Build (required before testing)+npm run build++# 3. Run specific test suites (recommended over full test)+npm run ci -- api-1 # API tests part 1+npm run ci -- api-2 # API tests part 2+npm run ci -- lint # Linting only+npm run ci -- client # Client tests++# 4. Run single test file+npm run mocha -- --exit --bail packages/tests/src/api/videos/single-server.ts++# 5. Full test suite (takes ~45-60 minutes, avoid unless necessary)+npm run test+```++**β οΈ Test Environment Notes:**+- Tests require PostgreSQL user with createdb/superuser privileges+- Some tests need Docker containers for S3/LDAP simulation+- Test failures often indicate missing system dependencies or DB permissions+- Set `DISABLE_HTTP_IMPORT_TESTS=true` to skip flaky import tests++### Validation Commands+```bash+# Lint code (runs ESLint + OpenAPI validation)+npm run lint++# Validate OpenAPI spec+npm run swagger-cli -- validate support/doc/api/openapi.yaml++# Build server+npm run build:server+```++## Project Architecture & Layout++### Server-Side Structure (Primary Focus)+```+server/core/+βββ controllers/api/ # Express route handlers (add new endpoints here)+β βββ index.ts # Main API router registration+β βββ videos/ # Video-related endpoints+β βββ users/ # User-related endpoints+βββ models/ # Sequelize database models+β βββ video/ # Video, channel, playlist models+β βββ user/ # User, account models+βββ lib/ # Business logic services+β βββ job-queue/ # Background job processing+β βββ emailer.ts # Email service+βββ middlewares/ # Express middleware+β βββ validators/ # Input validation (always required)+β βββ auth.ts # Authentication middleware+βββ helpers/ # Utility functions+βββ initializers/ # App startup and constants+```++### Key Configuration Files+- `package.json` - Main dependencies and scripts+- `server/package.json` - Server-specific config+- `eslint.config.mjs` - Linting rules+- `tsconfig.base.json` - TypeScript base config+- `config/default.yaml` - Default app configuration+- `.mocharc.cjs` - Test runner configuration++### Shared Packages (`packages/`)+```+packages/+βββ models/ # Shared TypeScript interfaces (modify for API changes)+βββ core-utils/ # Common utilities+βββ ffmpeg/ # Video processing+βββ server-commands/ # Test helpers+βββ tests/ # Test files+```++### Scripts Directory (`scripts/`)+- `scripts/build/` - Build automation+- `scripts/dev/` - Development helpers+- `scripts/ci.sh` - Continuous integration runner+- `scripts/test.sh` - Test runner++## Continuous Integration Pipeline++**GitHub Actions** (`.github/workflows/test.yml`):+1. **Matrix Strategy**: Tests run in parallel across different suites+2. **Required Services**: PostgreSQL, Redis, LDAP, S3, Keycloak containers+3. **Test Suites**: `types-package`, `client`, `api-1` through `api-5`, `transcription`, `cli-plugin`, `lint`, `external-plugins`+4. **Environment**: Ubuntu 22.04, Node.js 20.x+5. **Typical Runtime**: 15-30 minutes per suite++**Pre-commit Checks**: ESLint, TypeScript compilation, OpenAPI validation++## Making Code Changes++### Adding New API Endpoint+1. Create controller in `server/core/controllers/api/`+2. Add validation middleware in `server/core/middlewares/validators/`+3. Register route in `server/core/controllers/api/index.ts`+4. Update shared types in `packages/models/`+5. Add OpenAPI documentation tags+6. Write tests in `packages/tests/src/api/`++### Common Patterns to Follow+```typescript+// Controller pattern+import express from 'express'+import { apiRateLimiter, asyncMiddleware } from '../../middlewares/index.js'++const router = express.Router()+router.use(apiRateLimiter) // ALWAYS include rate limiting++router.get('/:id',+ validationMiddleware, // ALWAYS validate inputs+ asyncMiddleware(handler) // ALWAYS wrap async handlers+)+```++### Database Changes+1. Create/modify Sequelize model in `server/core/models/`+2. Generate migration in `server/core/initializers/migrations/`+3. Update shared types in `packages/models/`+4. Run `npm run build:server` to compile++## Validation Steps Before PR++1. **Build**: `npm run build` (must succeed)+2. **Lint**: `npm run lint` (must pass without errors)+5. **OpenAPI**: Validate if API changes made++## Common Error Solutions++**Build Errors:**+- "Cannot find module": Run `yarn install --frozen-lockfile`+- "PostgreSQL connection": Check PostgreSQL is running and extensions installed+- TypeScript errors: Check Node.js version (must be >=20.x)++**Test Errors:**+- Permission denied: Ensure PostgreSQL user has createdb/superuser rights+- Port conflicts: Stop other PeerTube instances+- Import test failures: Set `DISABLE_HTTP_IMPORT_TESTS=true`++**Development Issues:**+- "Client dist not found": Run `npm run build:client` (only if working on client features)+- Redis connection: Ensure Redis server is running+- Hot reload not working: Kill all Node processes and restart++## Trust These Instructions++These instructions have been validated against the current codebase. Only search for additional information if:+- Commands fail with updated error messages+- New dependencies are added to package.json+- Build system changes are detected+- You need specific implementation details not covered here++Focus on server-side TypeScript development in `server/core/` and ignore the `client/` directory unless explicitly working on frontend integration.diff --git a/client/.github/instructions/angular.instructions.md b/client/.github/instructions/angular.instructions.mdnew file mode 100644index 0000000000..8f26f48630--- /dev/null+++ b/client/.github/instructions/angular.instructions.md@@ -0,0 +1,104 @@+---+description: 'Angular-specific coding standards and best practices'+applyTo: 'src/app/**/*.ts, src/app/**/*.html, src/app/**/*.scss, src/app/**/*.css'+---++# Angular Development Instructions++Instructions for generating high-quality Angular applications with TypeScript, using Angular Signals for state management, adhering to Angular best practices as outlined at https://angular.dev.++## Project Context+- Latest Angular version (use standalone components by default)+- TypeScript for type safety+- Angular CLI for project setup and scaffolding+- Follow Angular Style Guide (https://angular.dev/style-guide)+- Use Angular Material or other modern UI libraries for consistent styling (if specified)++## Development Standards++### Architecture+- Use standalone components unless modules are explicitly required+- Organize code by feature modules or domains for scalability+- Implement lazy loading for feature modules to optimize performance+- Use Angular's built-in dependency injection system effectively+- Structure components with a clear separation of concerns (smart vs. presentational components)++### TypeScript+- Enable strict mode in `tsconfig.json` for type safety+- Define clear interfaces and types for components, services, and models+- Use type guards and union types for robust type checking+- Implement proper error handling with RxJS operators (e.g., `catchError`)+- Use typed forms (e.g., `FormGroup`, `FormControl`) for reactive forms++### Component Design+- Follow Angular's component lifecycle hooks best practices+- When using Angular >= 19, Use `input()` `output()`, `viewChild()`, `viewChildren()`, `contentChild()` and `viewChildren()` functions instead of decorators; otherwise use decorators+- Leverage Angular's change detection strategy (default or `OnPush` for performance)+- Keep templates clean and logic in component classes or services+- Use Angular directives and pipes for reusable functionality++### Styling+- Use Angular's component-level CSS encapsulation (default: ViewEncapsulation.Emulated)+- Prefer SCSS for styling with consistent theming+- Implement responsive design using CSS Grid, Flexbox, or Angular CDK Layout utilities+- Follow Angular Material's theming guidelines if used+- Maintain accessibility (a11y) with ARIA attributes and semantic HTML++### State Management+- Use Angular Signals for reactive state management in components and services+- Leverage `signal()`, `computed()`, and `effect()` for reactive state updates+- Use writable signals for mutable state and computed signals for derived state+- Handle loading and error states with signals and proper UI feedback+- Use Angular's `AsyncPipe` to handle observables in templates when combining signals with RxJS++### Data Fetching+- Use Angular's `HttpClient` for API calls with proper typing+- Implement RxJS operators for data transformation and error handling+- Use Angular's `inject()` function for dependency injection in standalone components+- Implement caching strategies (e.g., `shareReplay` for observables)+- Store API response data in signals for reactive updates+- Handle API errors with global interceptors for consistent error handling++### Security+- Sanitize user inputs using Angular's built-in sanitization+- Implement route guards for authentication and authorization+- Use Angular's `HttpInterceptor` for CSRF protection and API authentication headers+- Validate form inputs with Angular's reactive forms and custom validators+- Follow Angular's security best practices (e.g., avoid direct DOM manipulation)++### Performance+- Enable production builds with `ng build --prod` for optimization+- Use lazy loading for routes to reduce initial bundle size+- Optimize change detection with `OnPush` strategy and signals for fine-grained reactivity+- Use trackBy in `ngFor` loops to improve rendering performance+- Implement server-side rendering (SSR) or static site generation (SSG) with Angular Universal (if specified)++### Testing+- Write unit tests for components, services, and pipes using Jasmine and Karma+- Use Angular's `TestBed` for component testing with mocked dependencies+- Test signal-based state updates using Angular's testing utilities+- Write end-to-end tests with Cypress or Playwright (if specified)+- Mock HTTP requests using `HttpClientTestingModule`+- Ensure high test coverage for critical functionality++## Implementation Process+1. Plan project structure and feature modules+2. Define TypeScript interfaces and models+3. Scaffold components, services, and pipes using Angular CLI+4. Implement data services and API integrations with signal-based state+5. Build reusable components with clear inputs and outputs+6. Add reactive forms and validation+7. Apply styling with SCSS and responsive design+8. Implement lazy-loaded routes and guards+9. Add error handling and loading states using signals+10. Write unit and end-to-end tests+11. Optimize performance and bundle size++## Additional Guidelines+- Follow Angular's naming conventions (e.g., `feature.component.ts`, `feature.service.ts`)+- Use Angular CLI commands for generating boilerplate code+- Document components and services with clear JSDoc comments+- Ensure accessibility compliance (WCAG 2.1) where applicable+- Use Angular's built-in i18n for internationalization (if specified)+- Keep code DRY by creating reusable utilities and shared modules+- Use signals consistently for state management to ensure reactive updatesdiff --git a/client/.github/instructions/copilot-instructions.md b/client/.github/instructions/copilot-instructions.mdnew file mode 100644index 0000000000..9b2a79ddc4--- /dev/null+++ b/client/.github/instructions/copilot-instructions.md@@ -0,0 +1,112 @@+# PeerTube Client Development Instructions for Coding Agents++## Client Overview++This is the Angular frontend for PeerTube, a decentralized video hosting platform. The client is built with Angular 20+, TypeScript, and SCSS. It communicates with the PeerTube server API and provides the web interface for users, administrators, and content creators.++**Key Technologies:**+- Angular 20+ with standalone components+- TypeScript 5++- SCSS for styling+- RxJS for reactive programming+- PrimeNg and Bootstrap for UI components+- WebdriverIO for E2E testing+- Angular CLI++## Client Build and Development Commands++### Prerequisites (for client development)+- Node.js 20++- yarn 1+- Running PeerTube server (see ../server instructions)++### Essential Client Commands++```bash+# From the client directory:+cd /client++# 1. Install dependencies (ALWAYS first)+yarn install --pure-lockfile++# 2. Development server with hot reload+npm run dev++# 3. Build for production+npm run build+```++### Client Testing Commands+```bash+# From client directory:+npm run lint # ESLint for client code+```++### Common Client Issues and Solutions++**Angular Build Failures:**+- Always run `yarn install --pure-lockfile` after pulling changes+- Clear `node_modules` and reinstall if dependency errors occur+- Build may fail on memory issues: `NODE_OPTIONS="--max-old-space-size=4096" npm run build`+- Check TypeScript errors carefully - Angular is strict about types++**Development Server Issues:**+- Default port is 3000, ensure it's not in use+- Hot reload may fail on file permission issues+- Clear browser cache if changes don't appear++## Client Architecture and File Structure++### Client Directory Structure+```+/src/+ /app/+ +admin/ # Admin interface components+ +my-account/ # User account management pages+ +my-library/ # User's videos, playlists, subscriptions+ +search/ # Search functionality and results+ +shared/ # Shared Angular components, services, pipes+ +standalone/ # Standalone Angular components+ +videos/ # Video-related components (watch, upload, etc.)+ /core/ # Core services (auth, server, notifications)+ /helpers/ # Utility functions and helpers+ /menu/ # Navigation menu components+ /assets/ # Static assets (images, icons, etc.)+ /environments/ # Environment configurations+ /locale/ # Internationalization files+ /sass/ # Global SCSS styles+```++### Key Client Configuration Files++- `angular.json` - Angular CLI workspace configuration+- `tsconfig.json` - TypeScript configuration for client+- `e2e/wdio*.conf.js` - WebdriverIO E2E test configurations+- `src/environments/` - Environment-specific configurations++### Shared Code with Server (`../shared/`)++The client imports TypeScript models and utilities from the shared directory:+- `../shared/models/` - Data models (Video, User, Channel, etc.). Import these in client code: `import { Video } from '@peertube/peertube-models'`+- `../shared/core-utils/` - Utility functions shared between client/server. Import these in client code: `import { ... } from '@peertube/peertube-core-utils'`+-++## Client Development Workflow++### Making Client Changes++1. **Angular Components:** Create/modify in `/src/app/` following existing patterns+2. **Shared Components:** Reusable components go in `/src/app/shared/`+3. **Services:** Core services in `/src/app/core/`, feature services with components+4. **Styles:** Component styles in `.scss` files, global styles in `/src/sass/`+5. **Assets:** Images, icons in `/src/assets/`+6. **Routing:** Routes defined in feature modules or `app-routing.module.ts`++## Trust These Instructions++These instructions are comprehensive and tested specifically for client development. Only search for additional information if:+1. Commands fail despite following instructions exactly+2. New error messages appear that aren't documented here+3. You need specific Angular implementation details not covered above++For server-side questions, refer to the server instructions in `../.github/copilot-instructions.md`.