diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 000000000..a219e7b44 --- /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.md new file mode 100644 index 000000000..8f26f4863 --- /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 updates diff --git a/client/.github/instructions/copilot-instructions.md b/client/.github/instructions/copilot-instructions.md new file mode 100644 index 000000000..9b2a79ddc --- /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`.