Thanks for helping. This page covers setup, the rules the code follows, and how to send a change.
Requirements: Node 20 or newer (22 recommended, see .nvmrc), ffmpeg with libx264, and Google Chrome for the dashboard browser tests.
git clone https://github.com/edison16a/Content-Machine.git
cd Content-Machine
npm install # also builds every package
npm run cm -- doctor # checks ffmpeg, the font, Chrome and logos
npm run check # lint, typecheck, build, unit and integration testsBrowser tests need the demo project:
npm run demo
npm run test:e2e- Dependency direction.
cliusesrenderanddashboard; those usecore;coreuses nothing else and stays pure (no filesystem, processes, network or clock). Lint andtest/architecture.test.tsenforce it. See docs/architecture.md. - Strict TypeScript. No
any, no default exports in packages, named exports only. - Small files. Aim for functions under 50 lines and files under about 200. Explain non-obvious code with a comment that says why.
- Schemas first. Every JSON file on disk has a zod schema in
packages/core/src/schemas. After changing one, runnpm run docs:schemasand commit the result (CI fails on drift). - Specs and code move together. If you change behavior described in
docs/specs/, update the spec in the same pull request. - Never add another way to download video (everything goes through
fetchand yt-dlp), process audio, or hand-edit generated files (plan/schedule.json,dashboard.html,projects/dashboard-data.js). - Writing style for docs and UI text: short sentences and plain words. No em dashes or arrows standing in for words.
- Pure logic gets unit tests.
corekeeps at least 90% coverage. - Anything that runs ffmpeg gets an integration test on synthetic video (skipped when ffmpeg is missing).
- Dashboard behavior gets a Playwright test in
packages/dashboard/e2e.
- Use conventional commits (
feat:,fix:,docs:,test:,chore:,ci:), one logical change per commit. - Run
npm run checkbefore pushing. - Fill in the pull request template, including what you tested.
By contributing you agree that your work is released under the MIT License and that you follow the Code of Conduct.