Development
Setup
nvm use # Node 26 (.nvmrc)npm installnpm run dev # electron-vite with HMRSupported platforms: Linux x64 and Windows x64. mkvtoolnix is not required on your machine: install the sidecars from the app (onboarding or Settings → Video tools).
Scripts
| Script | Purpose |
|---|---|
npm run dev |
Electron with HMR |
npm test / test:watch |
Vitest (Main in Node, renderer in jsdom) |
npm run typecheck |
tsc for main/preload (node) and renderer (web) |
npm run lint / format |
ESLint / Prettier |
npm run db:generate |
Generate a Drizzle migration from src/main/database/schema |
npm run db:check |
Validate migration consistency |
npm run build |
Typecheck + electron-vite build |
npm run dist:linux / dist:win |
Package on a native runner (used by CI) |
npm run build:win |
Build the Windows installer from Linux (wine in Docker) |
npm run build:all |
Linux + Windows locally |
npm run icons |
Regenerate icons from resources/icon.svg |
npm run clean |
Remove out/, dist/ and the ESLint cache |
Before opening a pull request
npm run lint && npm run typecheck && npm test && npm run db:checkCI (.github/workflows/release.yml) only runs on tags and manual dispatch, so run these locally.
Conventions
- Process boundaries: the renderer never touches Node or Electron. A new capability means a channel in
src/shared/ipc-contract.ts, a handler built withcreateHandler(Zod validation), the preload allowlist and a typed hook insrc/renderer/src/data/. Seeipc.md. - Main process: separation of concerns (repositories, services, parsers, lexers). Keep logic that does not need
electronin plain modules so it is testable in Node. - Subtitles: only text nodes reach the LLM; the AST must reassemble the file byte for byte, preserving timestamps and tags. A parser change needs round-trip tests. See
parsing.md. - External processes: always through
ProcessRunner(timeout, SIGTERM → SIGKILL, tracked for shutdown). Never callchild_processdirectly. - Database: change the schema in
src/main/database/schema, runnpm run db:generateand commit the migration. Seedatabase.md. - UI text: no user-facing text from the Main, only error codes. Strings go through i18next (English is the source language,
pt-BRis complete), typed keys. Seerenderer.md. - Secrets: the OpenRouter key never leaves the Main process in clear text, and logs go through the redactor. See
logging.md. - Docs: update the matching file in
docs/in the same change.README.mdandREADME-pt.mdare for end users; technical detail belongs here.
Tests
- Vitest, with property tests (
fast-check) in the parsers. - Renderer tests start with
// @vitest-environment jsdomand usetest/fake-api.ts, a typedwindow.apiwhere every unmocked call rejects. Seerenderer.md. - Manifest changes are validated by
src/main/sidecars/manifest.schema.test.ts.
Releasing
See release.md.