obelisk/docs/adr/0005-app-electron-vite-ts-esm.md

# The app builds with electron-vite (TS + ESM), packages with electron-builder

**Context.** The desktop app must consume the shared TypeScript/ESM Core
(`providers/*` + `persist`) instead of maintaining its own duplicate indexer, and
the app itself should be TypeScript + ESM long-term. The app previously ran raw
CommonJS on Electron's Node with only the Vue renderer built by Vite; the main
process had no build step, and Electron's bundled Node (20 on Electron 33) can
neither strip TypeScript nor use `node:sqlite`. Options for the main-process build
were a hand-rolled tsc/esbuild step, `vite-plugin-electron`, or `electron-vite`.

**Decision.** Adopt **electron-vite** to build all three processes (main, preload,
renderer) as TypeScript + ESM, and keep **electron-builder** for packaging
(dmg/nsis/AppImage). electron-vite is purpose-built for the Electron three-process
model and handles the parts a DIY build would force us to hand-maintain forever
(per-process module format, native-module externalization, dev reload). Specific
decisions within this:

- **Preload is emitted as CommonJS** even though the app is ESM: the sandboxed
  renderer (sandbox is on by default since Electron 20, and we keep it on for
  security) does not support ESM preload. Source stays ESM; only the preload
  output format is CJS. `main` loads `../preload/index.js`.
- **The app consumes the Core from source**: electron-vite/rollup bundles
  `packages/core/src/providers/*` + `packages/core/src/persist.ts` (and their
  `packages/core/src/parsing.ts` dependency) into the app's main/worker build,
  injecting `better-sqlite3`. This
  works because the provider→parsing import graph is node:sqlite-free (ADR-0001),
  so nothing drags `node:sqlite` into the app. The `dist/` from `build:core`
  (ADR-0003) remains for the CLI package; the app does not need it.
- **better-sqlite3 stays the app's binding**, externalized (not bundled) and
  unpacked from the asar.
- **The app main + preload source is TypeScript with types at its seams**, but
  under a *deliberately more lenient* project than the runtime core. `app/tsconfig.json`
  keeps `strict` on yet sets `noImplicitAny: false`, because the app mostly
  orchestrates the already-strictly-typed core (`packages/core/src/`), and annotating every
  internal SQLite-handle helper would be high-cost, low-value churn. Types are
  added where they matter: the core-consumption seam (`BuildIndexOptions`/
  `BuildIndexResult`, `FileInfo`), the service/worker factories, and the IPC
  bridge. Module-to-module specifiers use the real `.ts` extension (mirroring
  Core source, since Node's type-stripping does not rewrite `.js`→`.ts`), which
  needs `allowImportingTsExtensions` (safe under the project's `noEmit`); the
  worker's *runtime* path stays `indexer-worker.js` because that is the built
  output. `@types/better-sqlite3` is a devDependency for the injected binding.

**Two-tier typechecking.** `npm run typecheck` runs the root project (`packages/core/src/` +
`tests/`, fully strict including `noImplicitAny`) and then the app project. The
root project **excludes the app-importing tests** (`tests/app-*.test.mjs`,
`tests/recap-capture-query.test.mjs`): those tests import app source, which would
otherwise drag the lenient app files into the strict root program and fail on
implicit `any`. The app source is instead covered by `app/tsconfig.json`, so
nothing loses type coverage — the strict core and the lenient app are checked by
the project that owns each, and never mixed.

**Consequences.** The app is restructured into `src/{main,preload,renderer}` with
`electron.vite.config.ts`; each main module is a build input so relative imports
between them and the indexer worker (`{ type: 'module' }`) resolve at runtime.
`npm run dev` is `electron-vite dev`. Tests that loaded app modules moved
to ESM imports, and `app-main-settings` was rewritten from CJS `Module._load`
mocking to `node:test` `mock.module` (needs `--experimental-test-module-mocks`).
A future contributor may be tempted to make the preload ESM or disable the
sandbox — this ADR records that CJS preload under an on sandbox is the intended,
secure default.