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

auto-git:

Browse Source 
[change] AGENTS.md
 [change] docs/tauri-migration.md
This commit is contained in:
Victor Giers
2026-05-06 05:40:48 +02:00
parent 7142cf6395
commit cbc1c34ced
2 changed files with 59 additions and 41 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
AGENTS.md
View File

@@ -30,8 +30,9 @@ A future migration to Tauri is planned, but do not begin that migration unless t
- `scripts/` - development wrappers used by npm scripts.
- `scripts/run-backend.cjs` starts Uvicorn from `backend/.venv`.
- `scripts/run-electron-dev.cjs` waits for Vite and FastAPI, then launches Electron.
- `scripts/run-tauri-dev.cjs` starts or reuses FastAPI, then launches the Tauri dev shell.
- `run.sh` - bootstrap script for local development dependencies and dev startup.
- `vite.config.js` - Vite dev/build configuration. Dev server is fixed at `127.0.0.1:5173`.
- `vite.config.js` - Vite dev/build configuration. Electron dev uses `127.0.0.1:5173`; Tauri dev uses an additive strict Vite port at `127.0.0.1:5174`.
## Run and Build Commands
@@ -39,8 +40,10 @@ A future migration to Tauri is planned, but do not begin that migration unless t
- `npm run dev` - start backend, Vite renderer, and Electron together.
- `npm run dev:backend` - start FastAPI on `127.0.0.1:8000` with reload. Requires `backend/.venv`.
- `npm run dev:renderer` - start Vite on `127.0.0.1:5173`.
- `npm run dev:renderer:tauri` - start Vite on `127.0.0.1:5174` for Tauri.
- `npm run dev:electron` - wait for Vite and backend health, then start Electron.
- `npm run dev:tauri` - start the Tauri shell against the Vite renderer. The FastAPI backend is still external during migration work.
- `npm run dev:tauri` - start or reuse FastAPI on `127.0.0.1:8000`, start the Tauri Vite renderer on `127.0.0.1:5174`, then launch the Tauri shell.
- `npm run dev:tauri:shell` - launch the raw Tauri shell when backend lifecycle is managed separately.
- `npm run build` - build the renderer into `dist/`.
- `npm start` - start Electron against the current app files.
@@ -67,7 +70,7 @@ Do not edit or commit generated/runtime data unless the task explicitly requires
- `node_modules/` - npm dependencies.
- `dist/` - Vite build output.
- `__pycache__/`, `*.pyc`, `.DS_Store`, and similar machine-generated files.
- Local app settings files under the Electron user data directory or `HEIMGEIST_SETTINGS_FILE`.
- Local app settings files under the Electron user data directory, the Tauri app config directory, or `HEIMGEIST_SETTINGS_FILE`.
- Tauri-generated `src-tauri/target/`, `src-tauri/gen/`, and local `src-tauri/Cargo.lock` if generated by local verification.
Avoid broad file operations that traverse these directories. Use ignore patterns with search tools when inspecting the repo.
@@ -77,7 +80,7 @@ Avoid broad file operations that traverse these directories. Use ignore patterns
- Frontend changes: run `npm run build` at minimum. For UI or interaction changes, also run the dev stack and exercise the affected flow in Electron.
- Backend changes: run a targeted syntax/import check such as `backend/.venv/bin/python -m py_compile backend/main.py backend/local_rag.py` for touched modules, then start `npm run dev:backend` or the full dev stack and check `GET /health`.
- Desktop bridge/Electron changes: run the full dev stack with `npm run dev` and verify Electron launches, settings load/save, dialogs or shell actions work, and no renderer code bypasses `src/desktop/desktopApi.js`.
- Tauri desktop bridge changes: run `cargo check --manifest-path src-tauri/Cargo.toml` with a temp `CARGO_TARGET_DIR` when useful, run `npm run build`, and if practical run `npm run dev:tauri` with a temporary `HEIMGEIST_SETTINGS_FILE` so local user settings are not modified during verification.
- Tauri desktop bridge changes: run `cargo check --manifest-path src-tauri/Cargo.toml` with a temp `CARGO_TARGET_DIR` when useful, run `npm run build`, and if practical run `npm run dev:tauri`. Use a temporary `HEIMGEIST_SETTINGS_FILE` when testing ordinary shared settings behavior; use a temporary `HOME` with a fake Electron settings file when testing first-run import, because `HEIMGEIST_SETTINGS_FILE` intentionally bypasses import.
- API contract changes: verify both sides together. Update backend schemas/routes and renderer callers in the same change, then exercise the affected request path.
- RAG, Whisper, Ollama, or SearXNG changes: note any external services or local models required for verification, and test graceful failure paths when those services are unavailable.
@@ -88,6 +91,7 @@ Avoid broad file operations that traverse these directories. Use ignore patterns
- Keep Tauri renderer calls behind `src/desktop/desktopApi.js`; do not import Tauri APIs directly in React components.
- When adding desktop capabilities, prefer method names and payloads that could map cleanly to either Electron IPC or Tauri commands.
- Maintain Electron behavior while any Tauri work is incomplete. Electron remains the supported desktop shell until Tauri reaches feature parity for settings, file picking/opening, external links, update flow, window events, backend startup expectations, and packaging.
- During migration, Tauri settings should import Electron settings only on first run when Tauri settings do not already exist. Preserve `HEIMGEIST_SETTINGS_FILE` as an explicit shared override and do not move or rewrite `backend/app.db` or `backend/libraries`.
- Avoid refactors that mix migration prep with unrelated feature work. Migration work should be explicit and reviewable.
## Coding and Refactor Guidelines

88
docs/tauri-migration.md
View File

@@ -1,6 +1,6 @@
# Tauri Migration Spike
# Tauri Migration Notes
This spike adds an isolated Tauri v2 scaffold while keeping the Electron app as the supported desktop shell.
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.
References checked during the spike:
@@ -10,51 +10,65 @@ References checked during the spike:
- Tauri dialog plugin: https://v2.tauri.app/plugin/dialog/
- Tauri opener plugin: https://v2.tauri.app/plugin/opener/
## Current Electron Responsibilities
## Current Desktop Responsibility Map
| Area | Current Electron implementation | Tauri target |
| Area | Electron implementation | Tauri status |
| --- | --- | --- |
| Main app window | `BrowserWindow` in `electron/main.cjs`, loading Vite in dev and `dist/index.html` in production | `src-tauri/tauri.conf.json` window loading the same Vite dev URL or `../dist` |
| Settings window | Separate modal `BrowserWindow` routed to `#/settings` | Later phase: either a second Tauri webview window or in-app settings route |
| Settings persistence | JSON file under Electron `app.getPath('userData')`, with migrations and normalization | Implemented for Tauri with `HEIMGEIST_SETTINGS_FILE` override or app config `settings.json`; keys and normalizers mirror Electron closely |
| 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 for Tauri through the official dialog plugin; supports existing `title` and `filters` options |
| Open file/path | `shell.openPath` via `open-path` IPC | Implemented for Tauri through the official opener plugin |
| External links | `shell.openExternal` and `setWindowOpenHandler` | Implemented for Tauri through the official opener plugin for `http`, `https`, `mailto`, and `tel` URLs |
| Window focus events | Electron `focus` event forwarded to renderer | Implemented for Tauri by emitting `window-focused` and listening from `desktopApi` |
| App menu | Electron `Menu.buildFromTemplate` | Later phase: Tauri menu API |
| UI scale | Electron `webContents.setZoomFactor` | Later phase: Tauri/webview equivalent or renderer CSS scale strategy |
| DevTools preference | Electron opens/closes DevTools in dev | Later phase: Tauri devtools behavior and persisted preference |
| 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 | Not part of this spike; later sidecar/package design |
| Packaging | Electron starts from `main` and existing npm scripts | Later phase: Tauri bundle config, icons, signing, backend sidecar |
| 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 |
## Scaffold Added
## Development Workflow
- `src-tauri/tauri.conf.json` points Tauri at the existing Vite renderer on `http://127.0.0.1:5173` and the existing `dist` build output.
- `src-tauri/src/main.rs` registers Tauri commands for settings, file picking, path opening, external link opening, focus events, and update placeholders.
- `src-tauri/capabilities/default.json` grants the main window core, dialog, and opener permissions used by this spike.
- `src-tauri/icons/icon.png` is a placeholder icon required by Tauri context generation.
- `src/desktop/desktopApi.js` still prefers Electron. When Electron is absent and Tauri is present, it invokes matching Tauri commands. Without either desktop bridge, it falls back to safe defaults so the renderer can mount.
- 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.
## Running The Spike
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.
- Normal Electron development remains `npm run dev`.
- After installing npm dependencies, Tauri development is `npm run dev:tauri`.
- The Tauri config starts only the Vite renderer; start the FastAPI backend separately when testing chat flows.
- If Vite is already running on `127.0.0.1:5173`, reuse it with `npm run tauri -- dev --config '{"build":{"beforeDevCommand":""}}'`.
## 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.
- 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.
## Current Tauri Scaffold
- `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.
## Intentional Non-Goals
- No Electron files, scripts, or IPC behavior were removed.
- No Python backend sidecar, packaging, or lifecycle work was added.
- No Tauri updater, app menu, second settings window, UI zoom side effects, DevTools preference side effects, or packaging parity was implemented.
- 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.
## Remaining Parity Gaps
## Remaining Gaps Before Electron Removal
- Settings: UI scale side effects and DevTools preference side effects are not wired in Tauri yet.
- Settings window: Electron still has a separate modal settings window; Tauri currently uses the existing renderer route only.
- App menu: Electron menu roles are not recreated in Tauri.
- Update flow: startup/manual checks, changelog, restart, and signed release strategy.
- Backend lifecycle: FastAPI startup, health gating, ffmpeg/ffprobe environment, shutdown, and sidecar packaging.
- Packaging: bundle metadata, icons, signing/notarization, auto-update channel, and platform install behavior.
- 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.