# Entwicklung

Das Oleafly-Desktop-Repository einrichten, seine gepinnten Sidecars abrufen, die App ausführen und die wichtigsten Erweiterungspunkte verstehen.

Oleafly ist eine [Tauri 2](https://tauri.app)-Desktop-App. Das React- und TypeScript-Frontend spricht über Tauri IPC mit Rust. Rust verwaltet Projektdateien, das Kompilieren, Secrets, MCP-Routing und Anfragen an KI-Anbieter.

## Aufbau des Repositorys

```
Oleafly/
├── src/                    React app shell (stores, Tauri client, UI kit, port adapters)
│   ├── components/         ui (shadcn-style), layout, editor glue, preview panes, ai
│   ├── contributions/      registers rail tabs / commands / AI toolsets into the registry
│   ├── features/           compile, synctex, export
│   ├── lib/                tauri wrappers, github, spellcheck, utils, package shims
│   └── store/              zustand stores
├── packages/               @oleafly/* frontend packages consumed as TS source
│   ├── latex/  latex-intelligence/  ai-core/  ai-tools/  registry/
│   └── editor/  preview/  diagram/  preflight/  pdf-to-latex/  templates/  wysiwyg/
├── crates/
│   └── oleafly-agent/      provider clients, streaming, and agent orchestration
├── src-tauri/
│   ├── src/                Tauri commands, engines, config, Git, MCP, paths, projects
│   ├── binaries/           fetched Tectonic, Biber, and Typst sidecars
│   ├── resources/          templates, dictionaries, TeX data, language servers
│   └── tauri.conf.json
├── scripts/fetch-tectonic.sh
├── scripts/fetch-biber.sh
├── scripts/fetch-typst.sh
├── scripts/fetch-language-servers.mjs
└── docs/
```

Das Frontend ist ein pnpm-Workspace. Wiederverwendbare Features liegen in `packages/*` hinter injizierten Ports, und die App-Shell verdrahtet sie miteinander. Lesen Sie [Frontend-Architektur](/docs/engineering/architecture/), bevor Sie `packages/` anfassen: der Text erklärt das Port-Muster, die Contribution-Registry und die Alias-Verdrahtung.

## Voraussetzungen

- Node.js 22.13+ und pnpm 11.9+ (die genaue pnpm-Version ist in
  `package.json` deklariert)
- Rust (stable) über [rustup](https://rustup.rs)
- [Tauri-2-Systemabhängigkeiten](https://v2.tauri.app/start/prerequisites/) für Ihr Betriebssystem
- Optional bei der Einrichtung: [pandoc](https://pandoc.org/installing.html) für die Kompilierung von Markdown zu PDF und den Dokumentexport (die App kann ihre gepinnte Version bei Bedarf selbst installieren)

## Erster Start

```bash
pnpm install
./scripts/fetch-tectonic.sh all
./scripts/fetch-biber.sh all
./scripts/fetch-typst.sh all
pnpm language-servers:fetch
pnpm tauri dev
```

Für eine einzelne Plattform übergeben Sie deren Rust-Target-Triple an jedes Shell-Abrufskript. Mit `rustc -vV` finden Sie das Triple des Hosts. Der Language-Server-Befehl wählt den aktuellen Host, außer Sie übergeben ein Ziel an das zugrunde liegende Skript.

## Im Alltag

```bash
pnpm tauri dev          # run the app with hot reload (frontend) + cargo incremental (backend)
pnpm build              # typecheck + build the frontend (tsc -b && vite build)
pnpm tauri build        # produce a distributable bundle
```

### Prüfungen vor einem Pull-Request

Führen Sie die einschlägigen lokalen Prüfungen aus, bevor Sie einen Pull-Request öffnen:

```bash
pnpm build                                # frontend typecheck (noUnusedLocals/Parameters on)
pnpm test                                 # vitest across src/ and packages/
pnpm audit --prod --audit-level high      # registry-backed npm advisory check
cargo check --workspace --all-targets     # Rust workspace compiles
cargo deny --manifest-path src-tauri/Cargo.toml check  # Rust advisories, licenses, and sources
```

Die beiden Audit-Befehle brauchen Zugriff auf die Registry und das Netzwerk. CI zeichnet ihre aktuellen Ergebnisse bei jeder Codeänderung auf. Ein lokaler Lauf ohne Netzwerk kann nicht bestätigen, dass der Abhängigkeitsgraph frei von Advisories ist.

Führen Sie bei Änderungen, die Benutzer sehen, zusätzlich die End-to-End-Suite gegen die echte App und den echten Compiler aus. Siehe [e2e/README.md](https://github.com/Oleafly/Oleafly/blob/main/e2e/README.md).

```bash
pnpm test:e2e:app                         # builds + launches the app, runs Playwright, tears down
```

## Wie ein Kompiliervorgang abläuft

1. Das Frontend lädt den `project_engine`-Deskriptor des Backends und seine Capability-Flags und ruft dann `compileProject(projectId, mainDoc, offline)` über Tauri IPC auf.
2. Rust dispatcht über `DocumentEngine`. UI-Code darf das Verhalten einer Engine nicht aus einem Dateinamen ableiten.
3. LaTeX nutzt standardmäßig das mitgelieferte Tectonic. Ein Projekt kann stattdessen pdfLaTeX, XeLaTeX oder LuaLaTeX über `latexmk` wählen. Eine vollständige System-TeX-Installation hat Vorrang vor Oleaflys verwaltetem TinyTeX. Der gemeinsame Detektor verlangt die Kern-Compiler, `latexmk`, `kpsewhich` und Biber, bevor er diesen Vorrang gewährt.
4. Typst führt genau die Version aus, die das Projekt in `project.json` pinnt: das mitgelieferte Sidecar, ein per Prüfsumme verifizierter Download oder ein System-`typst`, das diese Version meldet. Es kompiliert das ausgewählte `.typ`-Hauptdokument mit gut lesbaren Diagnosen und einem expliziten PDF-Ausgabepfad. Mit „Automatisch kompilieren“ hält Rust stattdessen einen `typst watch`-Prozess pro Projekt am Laufen (`src-tauri/src/typst_watch.rs`). `docs/typst-toolchain.md` im Desktop-Repository behandelt Auflösung, Pins und das passende Tinymist.
5. Markdown ruft Pandoc direkt für `.md`/`.markdown` auf, mit einem expliziten
   Ausgabepfad und `--pdf-engine=<absolute bundled Tectonic path>`. Pandocs
   Handbuch unterstützt ausdrücklich einen vollständigen PDF-Engine-Pfad. Ersetzen Sie
   das nicht durch ein implizites System-`pdflatex`, denn das paketierte Oleafly darf
   nicht von einer nicht deklarierten TeX-Installation abhängen. Der Prozess läuft mit
   dem Projektstamm als Arbeitsverzeichnis, damit relative Bilder, Bibliografiedateien
   und CSL-Dateien sowohl für Hauptdokumente im Stamm als auch für verschachtelte
   Hauptdokumente funktionieren.

Tauris [Sidecar-Dokumentation](https://v2.tauri.app/develop/sidecar/) definiert `bundle.externalBin`-Eingaben mit Target-Triple-Suffixen und legt das paketierte Sidecar zur Laufzeit unter seinem Namen ohne Suffix offen. Oleaflys Pandoc-Adapter findet die gepackte ausführbare Tectonic-Datei neben der ausführbaren Datei der Anwendung, passend zum Desktop-Bundle-Layout von Tauri. Unit-Tests decken die Kandidaten App-Bundle unter macOS sowie Cargo debug/release ab, während der Release-Workflow auf jedem Ziel das bereitgestellte Gegenstück ohne Suffix prüft.

Downloads von Tectonic, Biber, Typst und Language-Servern sind versioniert und mit Prüfsummen gepinnt. Ihre Abrufskripte prüfen die Archivstruktur und entpacken nur die gesichteten ausführbaren Dateien oder Ressourcenpfade. CI und Release-Builds verwenden dieselben Skripte.

6. Alle Engines streamen normalisierte Protokoll- und Fehlerereignisse. Rust gibt die Kompilier-Metadaten über JSON-IPC zurück. Das PDF selbst wird separat als rohe Binärdaten über IPC geholt, statt als Base64 in das Ergebnis eingebettet zu werden.
7. Das Frontend rendert die PDF-Bytes mit pdf.js und veröffentlicht die normalisierten Diagnosen in CodeMirror.

Engine-Deskriptoren bilden die Kompilierungsrichtlinie ab, dazu Formatierungs- und Quelltext-Preflight-Profile sowie Mengen von Features, Exportformaten und Vorlagenarten. Frontend-Verbraucher nutzen den fail-closed Deskriptor des Dateispeichers, statt aus Dateiendungen zu raten. Siehe die [Matrix der Dokument-Engines](https://github.com/Oleafly/Oleafly/blob/main/docs/document-engines.md).

Typst meldet `supports_synctex=true` und `supports_offline=true`, dazu `supports_isolated_compile=false`. Die Synchronisierung von Quelltext und PDF läuft über das zum Projekt passende Tinymist und braucht Tinymist 0.13.30 oder neuer; darum setzt `typst_toolchain::describe_project` `supports_synctex` für ein auf Typst 0.11 oder 0.12 gepinntes Projekt auf `false` herab (`typst_sync::supported_for_project`). Der Offline-Modus blockiert Typst-Paket-Downloads, ein Kompiliervorgang nutzt dann nur den gemeinsamen Paketzwischenspeicher und den Ordner `typst-packages` des Projekts. Die isolierte Kompilierung bleibt LaTeX vorbehalten: der TikZ-Figurenpfad lehnt Typst-Projekte ab, und die Figuren-Werkzeuge des Assistenten rendern Typst-Schnipsel, etwa eine CeTZ-Leinwand oder ein fletcher-Diagramm, stattdessen mit `render_typst_snippet`. Fügen Sie Engine-Verhalten erst hinzu, wenn die Fähigkeit des Backends wahrheitsgemäß ist. Fügen Sie keine UI-Ausnahmen anhand von Dateiendungen hinzu.

## Wo der Zustand liegt

- Konfiguration: `~/.oleafly/config.json` (`0600` unter Unix). Nicht vertrauliche
  Einstellungen liegen hier.
- Secrets: `~/.oleafly/ai-secrets.json` und
  `~/.oleafly/app-secrets.json`, verschlüsselt mit dem
  `~/.oleafly/ai-secrets.key`, das nur dem Eigentümer gehört. GitHub und MCP teilen
  sich `app-secrets.json`. Zugangsdaten für KI-Anbieter verwenden
  `ai-secrets.json`.
- Projekte: `~/.oleafly/projects/<id>/`, gewöhnliche Ordner mit `.git`.
- App-Protokoll: `~/.oleafly/app.log`.

## Wichtige Erweiterungspunkte

- KI-Anbieter hinzufügen → `crates/oleafly-agent/src/provider.rs` aktualisieren und dann seine Anzeige-Metadaten in `packages/ai-core/src/providers.ts` spiegeln. Der Katalog-Paritätstest hält die beiden Listen deckungsgleich.
- Tauri-Befehl hinzufügen → in `src-tauri/src/*.rs` deklarieren, in `src-tauri/src/lib.rs` registrieren, in `src/lib/tauri.ts` kapseln.
- Dokument-Engine hinzufügen → `DocumentEngine` in `src-tauri/src/document_engine.rs` implementieren, wahrheitsgemäße Fähigkeiten anzeigen, einen per Prüfsumme gepinnten Pfad für Sidecar-Abruf und Smoke-Test anlegen und den Deskriptor dann in UI-Steuerelementen verwenden.
- Projektvorlage hinzufügen → einen Ordner mit einem `template.json`-Manifest in `src-tauri/resources/templates/` ablegen (von der Engine unabhängige Vorlagen-Metadaten sind weiterhin geplante Arbeit).
- Werkzeug für die KI hinzufügen → `packages/ai-tools/src/tools.ts`. App-Dienste, die es braucht, laufen über `AiToolsHost` in `src/lib/ai-tools.ts`.
- Rail-Tab, Paletten- oder Omnibar-Befehl oder KI-Werkzeugsatz hinzufügen → in `src/contributions/` registrieren (siehe [Frontend-Architektur](/docs/engineering/architecture/#the-contribution-registry)).

## Interna zu Synchronisierung und GitHub

Der OAuth-Device-Flow läuft serverseitig in Rust (`src-tauri/src/github.rs`), weil die OAuth-Endpunkte CORS nicht erlauben. Die API-Aufrufe (api.github.com) erfolgen vom Frontend aus.

## Code-Stil

- TypeScript: Orientieren Sie sich am Bestehenden. Keine Kommentare, sofern nicht darum gebeten wird. Beachten Sie `noUnusedLocals`/`noUnusedParameters`.
- Rust: idiomatisch, kleine Befehle, freundlich formulierte Fehlermeldungen.
- UI: Tailwind v4 + Geist-Tokens. Verwenden Sie die Primitives `Button`, `Tooltip` und `Select` wieder.

## Veröffentlichen

Die Paketierung zielt auf macOS Apple Silicon, Windows x64, Linux x64 und Linux ARM64. Jeder Build lädt seine Compiler-Sidecars und die gebündelte Language-Server-Ressource herunter und prüft sie. Release-Builds unterstützen Apples Signieren und Notarisierung unter macOS sowie Azure Artifact Signing unter Windows. Siehe [Veröffentlichen](/docs/engineering/releasing/) und [Installieren](/docs/install/) für Benutzer.
