Contributing

Baseline

Contributions are expected to preserve the post-audit behavior of this repository:

secure outbound request policy
private-by-default relay endpoints
explicit auth secret requirements
Workers/OpenNext Cloudflare path
Android TV-only wrapper scope
Apple TV unsupported

Do not reintroduce permissive relay behavior, wildcard CORS, cookie forwarding, TLS verification bypasses, or public private-network fetches.

Prerequisites

Node.js 22+
npm 10+
Java 17 for Android builds
Android SDK for Android TV validation
Docker if you need to run the image/build checks locally

Install dependencies:

npm install

Development Commands

npm run dev
npm run lint
npm test
npm run test:e2e
npm run build
npm run cf:build
docker compose config
docker build -t kvideo .
cd android-tv && ./gradlew --no-daemon lint test assembleDebug assembleRelease

Required Checks Before a PR

At minimum, run the checks relevant to the code you changed. For broad or infrastructure-facing work, run the full matrix:

npm run lint
npm test
npm run build
npm run cf:build
npm audit --omit=dev
docker compose config
docker build -t kvideo .
cd android-tv && ./gradlew --no-daemon lint test assembleDebug assembleRelease

If you touch user flows, add or update Playwright smoke coverage in playwright.

Style Expectations

Keep changes scoped and intentional.
Prefer testable extraction over speculative abstraction.
Do not add fake compatibility aliases for insecure legacy behavior.
Do not depend on arbitrary file-length limits. CI-backed quality gates matter; line counts do not.
Keep documentation accurate to the actual runtime behavior of the branch.

Pull Requests

Each PR should include:

what changed
why it changed
risk areas
validation performed
any deployment/env var changes

If a change affects relay, auth, sync, IPTV, PWA behavior, Workers deployment, or Android TV, say so explicitly in the PR body.

2.0 KiB Raw Blame History