releases/.claude/rules/engine-core.md

paths
VideoDownloader.Core/** VideoDownloader.Server/**

엔진 · 서버 영역 규칙

플랫폼 중립

Core 는 net8.0 이다. WPF·Windows 전용 API 를 끌어들이지 않는다. Avalonia/MAUI 가 같은 엔진을 쓰므로 여기 들어간 Windows 의존은 크로스플랫폼 이관을 막는다. OS별 경로는 Platform/CorePaths.cs 를 통한다.

외부 프로세스 (ffmpeg 등)

Platform/ProcessModels.cs 의 실행 헬퍼를 쓴다. 직접 Process.Start 를 새로 쓰지 않는다. 그 헬퍼가 보장하는 것들을 우회하면 과거 버그가 재발한다:

• stdout/stderr 동시 드레인 — 안 읽으면 파이프 버퍼가 차서 ffmpeg 가 hang 한다
• 취소·실패 시 Kill(entireProcessTree: true) — 안 하면 좀비 프로세스가 남는다
• 인자는 배열 전달 — 문자열 연결 금지
• exit code ≠ 0 이면 예외 — 조용히 넘어가면 실패가 .ts 잔재로만 드러난다

취소

모든 장기 작업은 CancellationToken 을 끝까지 전달한다. 중간에 삼키지 않는다. Parallel.ForEachAsync 는 ParallelOptions.CancellationToken 에 넣는다 (Hls/HlsDownloader.cs:77 패턴).

동시성

세그먼트 병렬도는 AppConfig.Concurrency, 동시 다운로드 수는 MaxConcurrentDownloads(기본 3)로 제어한다. 하드코딩된 병렬도를 새로 만들지 않는다 — 소켓 고갈로 이어진다.

데이터 경로

사용자 데이터는 CorePaths 를 통해서만 접근한다. VD_DATA_DIR 환경변수 오버라이드가 E2E 테스트 격리의 공식 후크이므로, 경로를 직접 조립하면 테스트가 실사용자 폴더를 오염시킨다.

서버

Server 는 App 안에서 호스팅되는 라이브러리다. 포트 0 이면 빈 포트를 자동 할당한다. LAN 노출 API 이므로 인증·경로 검증을 우회하는 엔드포인트를 추가하지 않는다.