# Geliştirme

Oleafly masaüstü deposunu kurun, sabit sürümlü sidecar'larını getirin, uygulamayı çalıştırın ve başlıca genişletme noktalarını tanıyın.

Oleafly, [Tauri 2](https://tauri.app) tabanlı bir masaüstü uygulamasıdır. React ve TypeScript frontend'i, Rust ile Tauri IPC üzerinden konuşur. Proje dosyaları, derleme, gizli bilgiler, MCP yönlendirmesi ve AI sağlayıcı istekleri Rust'ın sorumluluğundadır.

## Depo düzeni

```
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/
```

Frontend bir pnpm çalışma alanıdır. Yeniden kullanılabilir özellikler, enjekte edilen portların arkasında `packages/*` altında yer alır; uygulama kabuğu bunları birbirine bağlar. `packages/` altına dokunmadan önce [Frontend mimarisi](/docs/engineering/architecture/) belgesini okuyun: port desenini, katkı kayıt sistemini ve takma ad bağlantılarını ele alır.

## Ön koşullar

- Node.js 22.13+ ve pnpm 11.9+ (kesin pnpm sürümü `package.json` içinde bildirilir)
- [rustup](https://rustup.rs) üzerinden Rust (stable)
- İşletim sisteminiz için [Tauri 2 sistem bağımlılıkları](https://v2.tauri.app/start/prerequisites/)
- Kurulum sırasında isteğe bağlı: Markdown PDF derlemesi ve belge dışa aktarımı için [pandoc](https://pandoc.org/installing.html) (uygulama, sabit sürümlü derlemesini gerektiğinde kurabilir)

## İlk çalıştırma

```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
```

Yalnızca tek bir platform için, her kabuk betiğine o platformun Rust hedef üçlüsünü geçirin. Ana makine üçlüsünü bulmak için `rustc -vV` komutunu kullanın. Dil sunucusu komutu, temelindeki betik aracılığıyla bir hedef geçirmediğiniz sürece geçerli ana makineyi seçer.

## Günlük komutlar

```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 açmadan önceki denetimler

Bir pull request açmadan önce ilgili yerel denetimleri çalıştırın:

```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
```

Bu iki denetim komutu kayıt defteri (registry) ve ağ erişimi gerektirir. CI, güncel sonuçlarını her kod değişikliğinde kaydeder. Çevrimdışı yapılan bir yerel çalıştırma, bağımlılık grafiğinde güvenlik bülteni (advisory) bulunmadığını doğrulayamaz.

Kullanıcıya görünür değişiklikler için, uçtan uca test paketini gerçek uygulama ve derleyiciye karşı da çalıştırın. Bakınız: [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
```

## Derleme nasıl çalışır

1. Frontend, backend'deki `project_engine` tanımlayıcısını ve yetenek bayraklarını yükler, ardından Tauri IPC üzerinden `compileProject(projectId, mainDoc, offline)` çağrısını yapar.
2. Rust, gönderimi `DocumentEngine` üzerinden yapar. Arayüz kodu, motor davranışını bir dosya adından çıkarmamalıdır.
3. LaTeX, varsayılan olarak yanında paketlenmiş Tectonic'i kullanır. Bir proje bunun yerine `latexmk` üzerinden pdfLaTeX, XeLaTeX veya LuaLaTeX seçebilir. Eksiksiz bir sistem TeX kurulumu, Oleafly'nin yönettiği TinyTeX'e göre önceliklidir. Paylaşılan algılayıcı, bu önceliği tanımadan önce çekirdek derleyicilerin ve `latexmk`, `kpsewhich` ile Biber'ın bulunduğunu ister.
4. Typst, projenin `project.json` içinde sabitlediği sürümü birebir çalıştırır: yanında paketlenmiş sidecar; sağlama toplamıyla doğrulanmış bir indirme ya da o sürümü bildiren bir sistem `typst`'ı. Seçili `.typ` ana belgesini, insan okuyabilen tanılamalar ve açık bir PDF çıktı yoluyla derler. Otomatik derleme açıkken Rust bunun yerine proje başına bir `typst watch` süreci tutar (`src-tauri/src/typst_watch.rs`). Masaüstü deposundaki `docs/typst-toolchain.md`; çözümlemeyi, sürüm sabitlemeyi ve eşleşen Tinymist'ı ele alır.
5. Markdown, Pandoc'u doğrudan `.md`/`.markdown` dosyalarına karşı çağırır; açık bir çıktı yolu ve `--pdf-engine=<absolute bundled Tectonic path>` (mutlak, yanında paketlenmiş Tectonic yolu) ile. Pandoc'un el kitabı tam bir PDF motoru yolunu açıkça destekler. Paketlenmiş Oleafly, bildirilmemiş bir TeX kurulumuna bağımlı olmamalıdır; bu yüzden bunu örtük bir sistem `pdflatex` ile değiştirmeyin. Süreç, çalışma dizini olarak proje kökünü kullanarak çalışır; böylece göreli görseller, kaynakça dosyaları ve CSL dosyaları hem kökteki hem iç içe yer alan ana belgeler için çalışır.

Tauri'nin [sidecar belgeleri](https://v2.tauri.app/develop/sidecar/), `bundle.externalBin` girdilerini hedef üçlüsü ekleriyle tanımlar ve paketlenmiş sidecar'ı çalışma zamanında ekesiz adı altında sunar. Oleafly'nin Pandoc adaptörü, o paketlenmiş Tectonic çalıştırılabilir dosyasını, Tauri'nin masaüstü paket düzeniyle eşleşecek biçimde uygulama çalıştırılabilir dosyasının yanında çözümler. Birim testleri macOS uygulama paketi ve Cargo hata ayıklama/sürüm adaylarını kapsar; sürüm iş akışı ise her hedefte hazırlanan ekesiz kardeş dosyayı denetler.

Tectonic, Biber, Typst ve dil sunucusu indirmeleri sürümlüdür ve sağlama toplamıyla sabitlenmiştir. Getirme betikleri arşiv yapısını doğrular ve yalnızca gözden geçirilmiş çalıştırılabilir ya da kaynak yollarını çıkarır. CI ve sürüm derlemeleri aynı betikleri kullanır.

6. Tüm motorlar normalleştirilmiş günlük/hata olayları akıtır. Rust, derleme üst verisini JSON IPC üzerinden döndürür. PDF'in kendisi, sonuç içinde base64 olarak gömülmesi yerine ayrı olarak ham ikili IPC ile alınır.
7. Frontend, PDF baytlarını pdf.js ile görüntüler ve normalleştirilmiş tanılamaları CodeMirror'a yayınlar.

Motor tanımlayıcıları; derleme ilkesinin yanı sıra biçimlendirme/kaynak ön denetimi profillerini ve özellik/dışa aktarma/şablon türü kümelerini modeller. Frontend tüketicileri, uzantılardan tahmin yürütmek yerine hataya kapalı (fail-closed) dosya deposu tanımlayıcısını kullanır. Bakınız: [belge motoru matrisi](https://github.com/Oleafly/Oleafly/blob/main/docs/document-engines.md).

Typst, `supports_synctex=true` ve `supports_offline=true` bildirir; `supports_isolated_compile=false` olarak. Kaynak ve PDF eşitlemesi projenin eşleşen Tinymist'ından geçer ve Tinymist 0.13.30 ya da sonrasını gerektirir; bu yüzden `typst_toolchain::describe_project`, Typst 0.11 veya 0.12'ye sabitlenmiş bir proje için `supports_synctex` değerini `false` yapar (`typst_sync::supported_for_project`). Çevrimdışı kip, Typst paket indirmelerini engeller; bu yüzden derleme o durumda yalnızca paylaşılan paket önbelleğini ve projenin `typst-packages` klasörünü kullanır. Yalıtılmış derleme yalnızca LaTeX'te kalır: TikZ şekil yolu Typst projelerini reddeder; asistanın şekil araçları, CeTZ tuvali ya da fletcher diyagramı gibi Typst kod parçalarını bunun yerine `render_typst_snippet` ile işler. Motor davranışını yalnızca backend yeteneği gerçeği yansıtır hale geldikten sonra ekleyin. Uzantı temelli arayüz istisnaları eklemeyin.

## Durumun tutulduğu yerler

- Yapılandırma: `~/.oleafly/config.json` (Unix'te `0600`). Gizli olmayan tercihler burada tutulur.
- Gizli bilgiler: `~/.oleafly/ai-secrets.json` ve `~/.oleafly/app-secrets.json`; yalnızca sahibinin okuyabildiği `~/.oleafly/ai-secrets.key` ile şifrelenir. GitHub ve MCP, `app-secrets.json` dosyasını paylaşır. AI sağlayıcı kimlik bilgileri `ai-secrets.json` dosyasını kullanır.
- Projeler: `~/.oleafly/projects/<id>/`; içinde `.git` bulunan sıradan klasörler.
- Uygulama günlüğü: `~/.oleafly/app.log`.

## Başlıca genişletme noktaları

- AI sağlayıcı eklemek için → `crates/oleafly-agent/src/provider.rs` dosyasını güncelleyin, ardından görüntüleme üst verisini `packages/ai-core/src/providers.ts` içinde yansıtın. Katalog eşlik testi iki listeyi hizalı tutar.
- Tauri komutu eklemek için → `src-tauri/src/*.rs` içinde bildirin, `src-tauri/src/lib.rs` içinde kaydedin, `src/lib/tauri.ts` içinde sarmalayın.
- Belge motoru eklemek için → `DocumentEngine`'i `src-tauri/src/document_engine.rs` içinde uygulayın, dürüst yetenekler açığa çıkarın, sağlama toplamıyla sabitlenmiş bir sidecar getirme/duman testi yolu ekleyin, ardından tanımlayıcıyı arayüz denetimlerinde kullanın.
- Proje şablonu eklemek için → içinde `template.json` bildirimi bulunan bir klasörü `src-tauri/resources/templates/` altına bırakın (motordan bağımsız şablon üst verisi hâlâ planlanan bir iştir).
- AI'ya araç eklemek için → `packages/ai-tools/src/tools.ts`. Gerektirdiği uygulama servisleri `src/lib/ai-tools.ts` içindeki `AiToolsHost` üzerinden geçer.
- Ray sekmesi / palet ya da omnibar komutu / AI araç takımı eklemek için → `src/contributions/` içinde kaydedin (bakınız: [Frontend mimarisi](/docs/engineering/architecture/#the-contribution-registry)).

## Eşitleme ve GitHub iç yapısı

OAuth uç noktaları CORS etkin olmadığı için OAuth cihaz akışı Rust içinde sunucu tarafında çalışır (`src-tauri/src/github.rs`). API çağrıları (api.github.com) frontend'den yapılır.

## Kodlama stili

- TypeScript: var olanı izleyin. İstenmedikçe yorum eklemeyin. `noUnusedLocals`/`noUnusedParameters` kurallarına uyun.
- Rust: deyimsel yazın; küçük komutlar, anlaşılır hata iletileri.
- Arayüz: Tailwind v4 + Geist belirteçleri. `Button`, `Tooltip` ve `Select` temel bileşenlerini yeniden kullanın.

## Yayımlama

Paketleme şu hedefleri derler: macOS Apple Silicon, Windows x64, Linux x64 ve Linux ARM64. Her derleme, kendi derleyici sidecar'larını ve yanında paketlenmiş dil sunucusu kaynağını getirip denetler. Sürüm derlemeleri macOS'ta Apple imzalama ve tasdiki (notarization), Windows'ta Azure Artifact Signing destekler. Bakınız: [yayımlama](/docs/engineering/releasing/) ve kullanıcı [kurulumu](/docs/install/).
