feat(desktop): switch to embedded sqlite and electron packaging

[rookedsysc]

What does this PR do?

• Migrates KanVibe from a Docker/PostgreSQL runtime to an embedded SQLite desktop runtime.
• Adds Electron + Electron Builder packaging so the app can be distributed as a desktop build and prepared for DMG/Homebrew release flows.
• Adds a Playwright login smoke test to verify the real button-click login flow end to end.
• Adds a native runtime preflight so startup fails clearly on the wrong runtime and stale better-sqlite3 binaries are handled more safely.
• Follows up on review feedback around session signing, packaged startup behavior, and CI/runtime hardening.

How is it implemented?

Embedded database runtime

• Replace the PostgreSQL connection flow with better-sqlite3 + TypeORM.
• Add runtime DB path resolution, bundled seed DB generation, and idempotent SQLite schema bootstrap logic.
• Remove Docker-based startup requirements from the CLI flow.

Desktop packaging

• Add Electron entrypoints and Electron Builder configuration.
• Boot the existing Next.js custom server inside Electron and open it through a desktop window.
• Add Linux headless hardening so desktop verification can run in CI-like environments without disabling the sandbox for all Linux users.
• Add a Homebrew Cask template and document the DMG/Homebrew release path.

Verification and workflow updates

• Add a Playwright login E2E that fills credentials, clicks the real login button, and asserts board access.
• Pin local validation to Node 24 and align project docs/scripts with that runtime.
• Ignore local automation state (.tooling, .omc, .codex/hooks) so verification artifacts do not pollute git status.
• Add a startup preflight that validates the runtime before better-sqlite3 is first loaded.

Important Changes

Embedded SQLite migration

Runtime DB bootstrap and seed generation

• Why: the app must run without Docker and carry its own local database.
• Files: src/lib/database.ts, src/lib/databasePaths.ts, src/lib/sqliteSchema.ts, scripts/build-seed-db.ts, src/lib/typeorm-cli.config.ts

SQLite-compatible entity updates

• Why: enum/json/uuid column definitions had to be made SQLite-safe while preserving current behavior.
• Files: src/entities/KanbanTask.ts, src/entities/PaneLayoutConfig.ts

Desktop packaging support

Electron runtime bootstrap

• Why: package the existing Next.js app as a desktop application without downgrading the current app structure.
• Files: electron/main.js, electron/preload.js, electron-builder.yml, server.ts, package.json

Distribution and release templates

• Why: make DMG and Homebrew release preparation part of the repository workflow.
• Files: distribution/homebrew/kanvibe.rb.template, README.md, docs/README.ko.md, docs/README.zh.md, docs/nextron-bundled-db-homebrew-app.mdx

Review follow-up hardening

Session signing secret separation

• Why: prevent the session cookie HMAC key from reusing the login password and keep generated secrets stable across restarts.
• Files: src/lib/auth.ts, .env.example, src/lib/__tests__/auth.test.ts

Packaged runtime and CI safety

• Why: avoid pnpm rebuild attempts inside packaged apps, keep Linux sandboxing enabled for desktop users, and isolate Playwright app data between concurrent runs.
• Files: scripts/ensure-native-runtime.cjs, electron/main.js, playwright.config.ts

Packaging and cleanup reliability

• Why: ensure packaged tsx alias resolution still finds tsconfig.json, remove dead request-cancellation state, and harden SQLite schema helpers against unsafe identifier interpolation.
• Files: electron-builder.yml, src/components/AiSessionsDialog.tsx, src/lib/sqliteSchema.ts

Validation

• node scripts/ensure-native-runtime.cjs under Node 24
• node scripts/ensure-native-runtime.cjs under Node 25 to verify fast failure guidance
• pnpm db:prepare
• pnpm build
• pnpm test:e2e:login
• pnpm check
• pnpm test
• pnpm exec tsc --noEmit
• pnpm exec vitest run src/lib/__tests__/auth.test.ts src/components/__tests__/AiSessionsDialog.test.tsx

[greptile-apps]

Greptile Summary

This PR is a significant architectural migration that replaces the Docker/PostgreSQL runtime with an embedded SQLite database and wraps the existing Next.js application in an Electron desktop shell for DMG/Homebrew distribution. The database layer swap is well-structured — entity columns are correctly migrated to SQLite-compatible types (simple-enum, simple-json, varchar(36)), the schema bootstrap is idempotent, and the seed-DB generation flow is clean. The Electron entrypoint correctly isolates the desktop server to 127.0.0.1 and uses a proper readiness poll before opening the window.

Key issues found (beyond those already in previous threads):

• --no-sandbox is applied to all Linux users, not just CI/headless environments. This removes Chromium's primary renderer security sandbox for every Linux desktop user. It should be gated on process.env.CI or the absence of DISPLAY.
• The Electron auto-rebuild path calls pnpm which is unavailable in a packaged app. If a native ABI mismatch is ever detected inside a distributed .app bundle, execFileSync("pnpm", …) will throw ENOENT, crashing startup with a confusing error instead of the intended human-readable guidance.
• Playwright appDataDir is a hardcoded /tmp/ path, causing test-state collisions when CI runs jobs concurrently.
• The E2E login test hardcodes credentials and Korean UI labels, making it brittle against environment-variable overrides and locale changes.
• safeSessionsData null-guard in AiSessionsDialog.tsx is unreachable — sessionsData is always initialised to a non-null object via createEmptySessionsResult.

Confidence Score: 3/5

• Needs two targeted fixes before merging to avoid a security regression on Linux and a startup crash in the packaged Electron app.
• The core migration (SQLite schema, entity changes, DB path resolution) is solid and the Electron bootstrap logic is well thought out. However the unconditional --no-sandbox on Linux is a real security regression for end-users, and the pnpm rebuild call inside a packaged app will crash instead of printing the intended guidance. These two P1 issues lower confidence meaningfully. The remaining issues (Playwright path, E2E credentials, dead null-check) are quality improvements that can be addressed in a follow-up if needed.
• electron/main.js (sandbox flag) and scripts/ensure-native-runtime.cjs (packaged-app rebuild path) need attention before this is shipped to end-users.

Important Files Changed

Filename	Overview
electron/main.js	New Electron entrypoint: boots the internal server, waits for readiness, and opens BrowserWindow. The unconditional --no-sandbox flag on Linux removes Chromium's security sandbox for all end-users, not just CI environments.
scripts/ensure-native-runtime.cjs	New preflight that validates the Node version and auto-rebuilds better-sqlite3 on ABI mismatch. The Electron rebuild path calls pnpm exec electron-builder install-app-deps which will fail with ENOENT in a packaged app where pnpm is not available.
src/lib/database.ts	Replaces PostgreSQL DataSource with better-sqlite3 + TypeORM, removes migration imports, and adds WAL mode / foreign-key pragmas. Logic is sound; ensureRuntimeDatabaseFile and ensureSqliteDatabaseReady are called before DataSource initialisation.
src/lib/sqliteSchema.ts	Idempotent SQLite bootstrap: creates tables, ensures additive columns, and exposes buildSeedDatabase. SQL template-literal injection concern was flagged in an earlier review thread; all current call sites use hardcoded literals so the immediate risk is low.
playwright.config.ts	New Playwright config for the login E2E suite. Uses a hardcoded /tmp/kanvibe-playwright-appdata directory that will conflict between concurrent CI jobs.
tests/e2e/login.spec.js	New E2E smoke test for the login flow. Hardcodes credentials and Korean UI labels, making it fragile if env vars differ or the default locale changes.
electron-builder.yml	New Electron Builder configuration. tsconfig.json omission was flagged in a prior thread. asar: false is intentional to allow the custom Next.js server to read packaged files at runtime.
src/components/AiSessionsDialog.tsx	Adds null-safe wrappers (createEmptySessionsResult, translateOptional) and refactors optional query/role args to avoid passing undefined as positional params. The safeSessionsData null guard is redundant since sessionsData is always initialised to a non-null object.

Sequence Diagram

sequenceDiagram
    participant U as User / OS
    participant E as electron/main.js
    participant B as boot.js
    participant P as ensure-native-runtime.cjs
    participant S as server.ts (Next.js)
    participant D as src/lib/database.ts
    participant DB as SQLite (.kanvibe/kanvibe.db)

    U->>E: Launch app
    E->>E: Set KANVIBE_DESKTOP, KANVIBE_APP_DATA_DIR,<br/>KANVIBE_SEED_DB_PATH, NODE_ENV
    E->>B: require(boot.js)
    B->>P: require(ensure-native-runtime.cjs)
    P->>P: Check Node major version
    P->>P: Try load better-sqlite3
    alt ABI mismatch
        P->>P: execFileSync pnpm rebuild / install-app-deps
        P->>P: Retry load better-sqlite3
    end
    B->>S: require(server.ts) via tsx
    S->>D: getDataSource() on first request
    D->>DB: ensureRuntimeDatabaseFile() — copy seed DB or create empty
    D->>DB: ensureSqliteDatabaseReady() — CREATE TABLE IF NOT EXISTS …
    D->>DB: DataSource.initialize()
    S-->>E: HTTP server listening on 127.0.0.1:PORT
    E->>E: waitForServer(http://127.0.0.1:PORT/ko/login)
    E->>U: BrowserWindow.loadURL(startUrl)

Loading

_{Last reviewed commit: "fix(native): add bet..."}

[greptile-apps]

Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.

[greptile-apps]

Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.

[greptile-apps]

Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.