diff --git a/AGENTS.md b/AGENTS.md index 3549e8a3f..d261cde34 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -15,9 +15,9 @@ This file provides guidance to coding agents working in this repository. - Meaningful changes include new or changed user-visible behavior, architecture or data-flow changes, non-obvious maintenance workflows, new setup/debugging steps, and new subsystem contracts or boundaries. - Skip doc updates for trivial refactors with unchanged behavior, formatting-only edits, and isolated test-only changes. - Prefer updating an existing authoritative doc before creating a new one: - 1. `README.md` for top-level developer or user workflows - 2. `docs/architecture/` for architecture, ownership, and behavior contracts - 3. the nearest module `README.md` for local usage or behavior + 1. `README.md` for top-level developer or user workflows + 2. `docs/architecture/` for architecture, ownership, and behavior contracts + 3. the nearest module `README.md` for local usage or behavior - Repo docs are canonical even when they were originally drafted by an LLM. External wiki pages are derivative or synthesis content unless explicitly promoted back into the repo. - The external wiki sync is one-way by default: repo docs -> external wiki `_repo-context/`. - If repo docs changed and `IPTVNATOR_WIKI_VAULT` is configured, run `pnpm wiki:export --mode changed` after the doc update. @@ -44,11 +44,11 @@ IPTVNATOR_TRACE_STARTUP=1 nx serve electron-backend ``` - Narrower trace flags: - - `IPTVNATOR_TRACE_IPC=1` traces renderer `window.electron.*` bridge calls - - `IPTVNATOR_TRACE_DB=1` traces DB worker requests and request-scoped DB events - - `IPTVNATOR_TRACE_SQL=1` traces SQLite statements in the main process and DB worker - - `IPTVNATOR_TRACE_WINDOW=1` traces BrowserWindow lifecycle and unresponsive events - - `IPTVNATOR_TRACE_RENDERER_CONSOLE=1` mirrors renderer console output into the Electron terminal + - `IPTVNATOR_TRACE_IPC=1` traces renderer `window.electron.*` bridge calls + - `IPTVNATOR_TRACE_DB=1` traces DB worker requests and request-scoped DB events + - `IPTVNATOR_TRACE_SQL=1` traces SQLite statements in the main process and DB worker + - `IPTVNATOR_TRACE_WINDOW=1` traces BrowserWindow lifecycle and unresponsive events + - `IPTVNATOR_TRACE_RENDERER_CONSOLE=1` mirrors renderer console output into the Electron terminal - GPU/compositor debugging: @@ -99,6 +99,7 @@ M3U playlists can contain radio channels identified by the `radio="true"` attrib - Radio detection in the video player template: `activeChannel.radio === 'true'` — this is a string comparison, not boolean Key files: + - `libs/ui/playback/src/lib/audio-player/audio-player.component.ts` — the audio player component - `libs/ui/playback/src/lib/audio-player/audio-player.component.scss` — cinematic hero styling - `libs/playlist/m3u/feature-player/src/lib/video-player/video-player.component.html` — template conditionals for radio vs video @@ -130,3 +131,27 @@ Key files: Repository-specific guidance for IPTVnator's Electron-first Xtream implementation, including feature/data-access boundaries, worker-backed DB flows, and Xtream loading/progress UX expectations. Use when working on Xtream routes, store/data-source logic, or Electron-backed Xtream import/search/delete behavior. File: `.codex/skills/xtream-electron/SKILL.md` + + + + +## General Guidelines for working with Nx + +- For navigating/exploring the workspace, invoke the `nx-workspace` skill first - it has patterns for querying projects, targets, and dependencies +- When running tasks (for example build, lint, test, e2e, etc.), always prefer running the task through `nx` (i.e. `nx run`, `nx run-many`, `nx affected`) instead of using the underlying tooling directly +- Prefix nx commands with the workspace's package manager (e.g., `pnpm nx build`, `npm exec nx test`) - avoids using globally installed CLI +- You have access to the Nx MCP server and its tools, use them to help the user +- For Nx plugin best practices, check `node_modules/@nx//PLUGIN.md`. Not all plugins have this file - proceed without it if unavailable. +- NEVER guess CLI flags - always check nx_docs or `--help` first when unsure + +## Scaffolding & Generators + +- For scaffolding tasks (creating apps, libs, project structure, setup), ALWAYS invoke the `nx-generate` skill FIRST before exploring or calling MCP tools + +## When to use nx_docs + +- USE for: advanced config options, unfamiliar flags, migration guides, plugin configuration, edge cases +- DON'T USE for: basic generator syntax (`nx g @nx/react:app`), standard commands, things you already know +- The `nx-generate` skill handles generator discovery internally - don't call nx_docs just to look up generator syntax + + diff --git a/CLAUDE.md b/CLAUDE.md index c060b18fa..e8f75d755 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -15,9 +15,9 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co - Meaningful changes include new or changed user-visible behavior, architecture or data-flow changes, non-obvious maintenance workflows, new setup/debugging steps, and new subsystem contracts or boundaries. - Skip doc updates for trivial refactors with unchanged behavior, formatting-only edits, and isolated test-only changes. - Prefer updating an existing authoritative doc before creating a new one: - 1. `README.md` for top-level developer or user workflows - 2. `docs/architecture/` for architecture, ownership, and behavior contracts - 3. the nearest module `README.md` for local usage or behavior + 1. `README.md` for top-level developer or user workflows + 2. `docs/architecture/` for architecture, ownership, and behavior contracts + 3. the nearest module `README.md` for local usage or behavior - Repo docs are canonical even when they were originally drafted by an LLM. External wiki pages are derivative or synthesis content unless explicitly promoted back into the repo. - The external wiki sync is one-way by default: repo docs -> external wiki `_repo-context/`. - If repo docs changed and `IPTVNATOR_WIKI_VAULT` is configured, run `pnpm wiki:export --mode changed` after the doc update. @@ -236,6 +236,7 @@ The Xtream Codes module uses NgRx Signal Store with a layered architecture: ``` File structure: + ``` apps/web/src/app/xtream-electron/ ├── stores/ @@ -263,6 +264,7 @@ apps/web/src/app/xtream-electron/ ``` Key patterns: + - **Feature stores**: Each `with*.feature.ts` uses `signalStoreFeature()` for focused functionality - **Facade pattern**: `XtreamStore` composes all features, maintaining backward compatibility - **Data source abstraction**: `IXtreamDataSource` interface with environment-specific implementations @@ -314,6 +316,7 @@ The M3U playlist module handles traditional M3U/M3U8 playlists with support for ``` Key radio behavior: + - Detection: `channel.radio === 'true'` (string from M3U `radio` attribute) - The audio player always renders inline — `shouldShowInlinePlayer` is bypassed for radio - EPG panel is conditionally hidden in the template when radio is active @@ -322,6 +325,7 @@ Key radio behavior: - Component: `libs/ui/playback/src/lib/audio-player/audio-player.component.ts` Channel List Component Structure (parent coordinator pattern): + ``` libs/ui/components/src/lib/channel-list-container/ ├── channel-list-container.component.ts # Parent - shared state coordinator @@ -332,6 +336,7 @@ libs/ui/components/src/lib/channel-list-container/ ``` Key patterns: + - **EnrichedChannel**: Pre-computed EPG data attached to channels for performance - **Parent coordinator**: Manages shared signals (`channelEpgMap`, `progressTick`, `favoriteIds`) - **Virtual scrolling**: CDK virtual scroll for 90,000+ channel lists @@ -339,6 +344,7 @@ Key patterns: - **Global progress tick**: Single 30s interval instead of per-item intervals State management via NgRx (`libs/m3u-state/`): + - `PlaylistActions`: loadPlaylists, addPlaylist, removePlaylist, parsePlaylist - `ChannelActions`: setChannels, setActiveChannel, setAdjacentChannelAsActive - `EpgActions`: setActiveEpgProgram, setCurrentEpgProgram, setEpgAvailableFlag @@ -388,6 +394,7 @@ Keep TypeScript files under **300 lines**. Hard maximum is **350–400 lines**. - When you notice a file already exceeds 350 lines, **proactively suggest a refactoring** (or perform it if the change is straightforward) — even if the immediate task is small. Typical split strategies: + - Angular components: extract child components, move logic to a dedicated service or store feature - Signal store features: split into smaller `with*` feature functions in separate files - Services: split by responsibility (e.g. separate API, transformation, and state concerns) @@ -402,6 +409,7 @@ This rule exists to keep the codebase navigable and reviewable. A 150-line file This project uses modern Angular signal-based APIs and patterns. **ALWAYS** use the following: - **Component Queries**: Use `viewChild()`, `viewChildren()`, `contentChild()`, `contentChildren()` instead of `@ViewChild`, `@ViewChildren`, `@ContentChild`, `@ContentChildren` decorators + ```typescript // ✅ Correct - Signal-based readonly menu = viewChild.required('menuRef'); @@ -413,6 +421,7 @@ This project uses modern Angular signal-based APIs and patterns. **ALWAYS** use ``` **Important**: When using signals in templates with properties that expect non-signal values, unwrap the signal by calling it: + ```html @@ -422,6 +431,7 @@ This project uses modern Angular signal-based APIs and patterns. **ALWAYS** use ``` - **Component Inputs/Outputs**: Use `input()` and `output()` functions instead of `@Input()` and `@Output()` decorators + ```typescript // ✅ Correct - Signal-based readonly title = input.required(); @@ -435,6 +445,7 @@ This project uses modern Angular signal-based APIs and patterns. **ALWAYS** use ``` - **Reactive State**: Use signal primitives for reactive state management + ```typescript // ✅ Use signal(), computed(), effect(), linkedSignal() readonly count = signal(0); @@ -448,12 +459,14 @@ This project uses modern Angular signal-based APIs and patterns. **ALWAYS** use ``` - **Host Bindings**: Use `@HostBinding()` and `@HostListener()` decorators (these don't have signal equivalents yet) + ```typescript @HostBinding('class.active') get isActive() { return this.active(); } @HostListener('click') onClick() { /* ... */ } ``` - **Control Flow**: Use `@if`, `@for`, `@switch` instead of `*ngIf`, `*ngFor`, `*ngSwitch` + ```typescript // ✅ Correct - Modern syntax @if (isLoggedIn()) { @@ -651,13 +664,23 @@ No formal migration system yet. Schema changes are applied via raw SQL in `conne -# General Guidelines for working with Nx +## General Guidelines for working with Nx +- For navigating/exploring the workspace, invoke the `nx-workspace` skill first - it has patterns for querying projects, targets, and dependencies - When running tasks (for example build, lint, test, e2e, etc.), always prefer running the task through `nx` (i.e. `nx run`, `nx run-many`, `nx affected`) instead of using the underlying tooling directly +- Prefix nx commands with the workspace's package manager (e.g., `pnpm nx build`, `npm exec nx test`) - avoids using globally installed CLI - You have access to the Nx MCP server and its tools, use them to help the user -- When answering questions about the repository, use the `nx_workspace` tool first to gain an understanding of the workspace architecture where applicable. -- When working in individual projects, use the `nx_project_details` mcp tool to analyze and understand the specific project structure and dependencies -- For questions around nx configuration, best practices or if you're unsure, use the `nx_docs` tool to get relevant, up-to-date docs. Always use this instead of assuming things about nx configuration -- If the user needs help with an Nx configuration or project graph error, use the `nx_workspace` tool to get any errors +- For Nx plugin best practices, check `node_modules/@nx//PLUGIN.md`. Not all plugins have this file - proceed without it if unavailable. +- NEVER guess CLI flags - always check nx_docs or `--help` first when unsure + +## Scaffolding & Generators + +- For scaffolding tasks (creating apps, libs, project structure, setup), ALWAYS invoke the `nx-generate` skill FIRST before exploring or calling MCP tools + +## When to use nx_docs + +- USE for: advanced config options, unfamiliar flags, migration guides, plugin configuration, edge cases +- DON'T USE for: basic generator syntax (`nx g @nx/react:app`), standard commands, things you already know +- The `nx-generate` skill handles generator discovery internally - don't call nx_docs just to look up generator syntax