giers10/Heimgeist
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

auto-git:

Browse Source 
[change] AGENTS.md
 [change] README.md
 [change] docs/tauri-migration.md
This commit is contained in:
Victor Giers
2026-05-06 06:00:00 +02:00
parent 514fde9cad
commit 8946f26813
3 changed files with 77 additions and 98 deletions
Download Patch File Download Diff File Expand all files Collapse all files

107
docs/tauri-migration.md
View File

@@ -1,74 +1,63 @@
# Tauri Migration Notes
Tauri is now the primary experimental development shell for Heimgeist. Electron remains intact as a fallback until the remaining desktop and packaging gaps are closed.
Tauri is now Heimgeist's active desktop shell for local development. The former desktop shell runtime files and npm scripts have been removed from active development code.
References checked during the spike:
## Current Development Workflow
- Tauri Vite setup: https://v2.tauri.app/start/frontend/vite/
- Tauri JavaScript API: https://v2.tauri.app/reference/javascript/api/
- Tauri CLI: https://v2.tauri.app/reference/cli/
- Tauri dialog plugin: https://v2.tauri.app/plugin/dialog/
- Tauri opener plugin: https://v2.tauri.app/plugin/opener/
- Primary dev command: `npm run dev`.
- Compatibility alias: `npm run dev:tauri`.
- The dev wrapper is `scripts/run-tauri-dev.cjs`.
- The wrapper starts or reuses FastAPI on `127.0.0.1:8000`, waits for `/health`, then launches Tauri.
- The Vite renderer runs on strict port `127.0.0.1:5174`.
- `npm run dev:tauri:shell` launches raw `tauri dev` when the backend lifecycle is managed separately.
## Current Desktop Responsibility Map
| Area | Electron implementation | Tauri status |
| --- | --- | --- |
| Main app window | `BrowserWindow` in `electron/main.cjs`, loading Vite in dev and `dist/index.html` in production | Implemented through `src-tauri/tauri.conf.json`; dev loads the same React/Vite renderer on the Tauri-specific port `5174` |
| Settings window | Separate modal `BrowserWindow` routed to `#/settings` | Later phase: either a second Tauri webview window or the existing in-app settings route |
| Settings persistence | JSON under Electron `app.getPath('userData')`, or `HEIMGEIST_SETTINGS_FILE` when set | Implemented with persistent JSON under Tauri app config, with a first-run Electron settings import when safe |
| Renderer bridge | `electron/preload.cjs` exposes `window.electronAPI`; renderer uses `src/desktop/desktopApi.js` | Implemented: `desktopApi` still prefers Electron and falls back to Tauri commands/listeners |
| File picker | `dialog.showOpenDialog` via `pick-paths` IPC | Implemented through the official Tauri dialog plugin; supports the existing `title`, `filters`, and `multiple` option shape where practical |
| Open file/path | `shell.openPath` via `open-path` IPC | Implemented through the official Tauri opener plugin |
| External links | `shell.openExternal` and `setWindowOpenHandler` | Implemented through the official Tauri opener plugin for `http`, `https`, `mailto`, and `tel` URLs |
| Window focus events | Electron `focus` event forwarded to renderer | Implemented by emitting `window-focused` from Tauri and listening in `desktopApi` |
| App menu | Electron `Menu.buildFromTemplate` | Basic Tauri default menu implemented; detailed Electron menu parity remains later work |
| UI scale | Electron `webContents.setZoomFactor` | Implemented for Tauri/browser-like runtimes through `desktopApi.applyUiScale`, which applies renderer CSS zoom while leaving Electron native zoom unchanged |
| DevTools preference | Electron opens/closes DevTools in dev | Later phase: no clean stable Tauri equivalent is wired yet |
| Updates/changelog | Git-based update check, pull, restart, and local changelog | Later phase: replace with Tauri updater or another signed update flow |
| Backend lifecycle | External Node scripts start FastAPI in dev | Development parity implemented by `scripts/run-tauri-dev.cjs`, which starts or reuses the existing FastAPI dev backend; Python sidecar packaging remains later |
| Packaging | Electron starts from `main` and existing npm scripts | Later phase: Tauri bundle config, icons, signing/notarization, and Python backend sidecar |
## Development Workflow
- Electron development remains unchanged: `npm run dev`.
- Tauri development is now `npm run dev:tauri` or `npm run dev:tauri:full`.
- The Tauri wrapper starts or reuses FastAPI on `127.0.0.1:8000`, waits for `/health`, then launches Tauri.
- Tauri uses its own strict Vite dev port: `127.0.0.1:5174`. This avoids conflicts with the existing Electron renderer port `5173`.
- The raw Tauri shell remains available as `npm run dev:tauri:shell`; use it only when the backend lifecycle is managed separately.
The Tauri dev backend is still the normal FastAPI backend started from the repository root through `scripts/run-backend.cjs`. That keeps chat history and local RAG data in the existing backend locations.
The development backend is still the normal FastAPI backend started from the repository root through `scripts/run-backend.cjs`.
## User Data Continuity
- Chats continue to use `backend/app.db` through the existing FastAPI backend. No database move, rewrite, or migration is part of this step.
- Local RAG libraries continue to use `backend/libraries` through the existing FastAPI backend. No library state is moved or rewritten.
- `HEIMGEIST_SETTINGS_FILE` remains an explicit shared settings override for both Electron and Tauri. When it is set, Tauri reads and writes that file directly and does not perform first-run import.
- Chats continue to use `backend/app.db` through the existing FastAPI backend.
- Local RAG libraries continue to use `backend/libraries` through the existing FastAPI backend.
- No database or library state is moved, rewritten, or migrated by the Tauri shell.
- `HEIMGEIST_SETTINGS_FILE` remains an explicit shared settings override. When set, Tauri reads and writes that file directly and skips first-run import.
- Without `HEIMGEIST_SETTINGS_FILE`, Tauri stores settings in its app config `settings.json`.
- On first Tauri run only, when the Tauri settings file does not exist, Tauri attempts to read Electron settings from the platform config directory, including the existing `Heimgeist/settings.json` path used by Electron.
- If Electron settings are found, Tauri migrates and normalizes them into the Tauri settings path.
- Existing Tauri settings are not replaced by Electron settings.
- On first Tauri run only, when the Tauri settings file does not exist, Tauri attempts to import the historical Electron settings file from the platform config directory, including `Heimgeist/settings.json`.
- Existing Tauri settings are never overwritten by imported settings.
## Current Tauri Scaffold
## Desktop Bridge Surface
- `src-tauri/src/main.rs` registers Tauri commands for settings, dialogs, path opening, external links, focus events, and update placeholders.
- `src-tauri/capabilities/default.json` grants the main window core, dialog, and opener permissions used by the scaffold.
- `src-tauri/tauri.conf.json` points Tauri at the existing Vite renderer on `http://127.0.0.1:5174` in dev and `../dist` for build output.
- `scripts/run-tauri-dev.cjs` is the full Tauri dev wrapper.
- `src/desktop/desktopApi.js` remains the only renderer bridge layer for Electron/Tauri desktop functions.
Renderer code should continue to call only `src/desktop/desktopApi.js` for desktop functions. That bridge owns direct access to the Tauri global and maps the renderer API to Tauri commands/events.
## Intentional Non-Goals
Current Tauri-backed desktop methods:
- No Electron files, scripts, dependencies, or IPC behavior were removed.
- No backend API contracts changed.
- No Python backend sidecar, production backend packaging, or data relocation was added.
- No Tauri updater, changelog parity, or restart flow was implemented.
- `getSettings`
- `setSetting`
- `updateSettings`
- `pickPaths`
- `openPath`
- `openExternalLink`
- `onWindowFocus`
- `offWindowFocus`
- `applyUiScale`
- update/changelog placeholders
## Remaining Gaps Before Electron Removal
## Historical Removal Notes
- Update flow: startup/manual update checks, changelog, restart, and signed release strategy.
- Production backend lifecycle: package the FastAPI backend, set ffmpeg/ffprobe paths, health gate startup, and shut down cleanly.
- DevTools preference: Electron honors `openDevToolsOnStartup`; Tauri currently documents this as an Electron-only setting.
- Settings window parity: Electron still has a separate settings modal; Tauri currently uses the existing renderer route.
- App menu parity: Tauri has a basic default menu, not the full Electron template.
- Packaging: bundle metadata, final icons, signing/notarization, updater channel, and installer behavior.
This pass removed the former Electron runtime and development entry points:
- `electron/main.cjs`
- `electron/preload.cjs`
- `scripts/run-electron-dev.cjs`
- Electron npm metadata, dependencies, and scripts from `package.json`
- Electron-specific branches from `src/desktop/desktopApi.js`
The only remaining Electron references should be historical migration documentation or the Tauri first-run settings import note.
## Remaining Production-Release Tasks
- Replace update/changelog placeholders with a signed Tauri update flow or another release strategy.
- Package the FastAPI backend as a sidecar or equivalent production process.
- Preserve ffmpeg/ffprobe environment handling for packaged audio transcription.
- Add production backend startup health gating and shutdown behavior.
- Finalize bundle metadata, icons, signing, notarization, and installer behavior.
- Decide whether the settings route needs a dedicated Tauri window for production parity.
- Expand the basic Tauri menu if product-specific app menu actions are needed.