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 (yeni sekmede açılır) 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
Bölüm başlığı “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 belgesini okuyun: port desenini, katkı kayıt sistemini ve takma ad bağlantılarını ele alır.
Ön koşullar
Bölüm başlığı “Ön koşullar”- Node.js 22.13+ ve pnpm 11.9+ (kesin pnpm sürümü
package.jsoniçinde bildirilir) - rustup (yeni sekmede açılır) üzerinden Rust (stable)
- İşletim sisteminiz için Tauri 2 sistem bağımlılıkları (yeni sekmede açılır)
- Kurulum sırasında isteğe bağlı: Markdown PDF derlemesi ve belge dışa aktarımı için pandoc (yeni sekmede açılır) (uygulama, sabit sürümlü derlemesini gerektiğinde kurabilir)
İlk çalıştırma
Bölüm başlığı “İlk çalıştırma”pnpm install./scripts/fetch-tectonic.sh all./scripts/fetch-biber.sh all./scripts/fetch-typst.sh allpnpm language-servers:fetchpnpm tauri devYalnı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
Bölüm başlığı “Günlük komutlar”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 bundlePR açmadan önceki denetimler
Bölüm başlığı “PR açmadan önceki denetimler”Bir pull request açmadan önce ilgili yerel denetimleri çalıştırın:
pnpm build # frontend typecheck (noUnusedLocals/Parameters on)pnpm test # vitest across src/ and packages/pnpm audit --prod --audit-level high # registry-backed npm advisory checkcargo check --workspace --all-targets # Rust workspace compilescargo deny --manifest-path src-tauri/Cargo.toml check # Rust advisories, licenses, and sourcesBu 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 (yeni sekmede açılır).
pnpm test:e2e:app # builds + launches the app, runs Playwright, tears downDerleme nasıl çalışır
Bölüm başlığı “Derleme nasıl çalışır”- Frontend, backend’deki
project_enginetanımlayıcısını ve yetenek bayraklarını yükler, ardından Tauri IPC üzerindencompileProject(projectId, mainDoc, offline)çağrısını yapar. - Rust, gönderimi
DocumentEngineüzerinden yapar. Arayüz kodu, motor davranışını bir dosya adından çıkarmamalıdır. - 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 velatexmk,kpsewhichile Biber’ın bulunduğunu ister. - Typst, projenin
project.jsoniç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 sistemtypst’ı. Seçili.typana belgesini, insan okuyabilen tanılamalar ve açık bir PDF çıktı yoluyla derler. Otomatik derleme açıkken Rust bunun yerine proje başına birtypst watchsüreci tutar (src-tauri/src/typst_watch.rs). Masaüstü deposundakidocs/typst-toolchain.md; çözümlemeyi, sürüm sabitlemeyi ve eşleşen Tinymist’ı ele alır. - Markdown, Pandoc’u doğrudan
.md/.markdowndosyaları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 sistempdflatexile 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 (yeni sekmede açılır), 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.
- 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.
- 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 (yeni sekmede açılır).
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
Bölüm başlığı “Durumun tutulduğu yerler”- Yapılandırma:
~/.oleafly/config.json(Unix’te0600). Gizli olmayan tercihler burada tutulur. - Gizli bilgiler:
~/.oleafly/ai-secrets.jsonve~/.oleafly/app-secrets.json; yalnızca sahibinin okuyabildiği~/.oleafly/ai-secrets.keyile şifrelenir. GitHub ve MCP,app-secrets.jsondosyasını paylaşır. AI sağlayıcı kimlik bilgileriai-secrets.jsondosyasını kullanır. - Projeler:
~/.oleafly/projects/<id>/; içinde.gitbulunan sıradan klasörler. - Uygulama günlüğü:
~/.oleafly/app.log.
Başlıca genişletme noktaları
Bölüm başlığı “Başlıca genişletme noktaları”- AI sağlayıcı eklemek için →
crates/oleafly-agent/src/provider.rsdosyasını güncelleyin, ardından görüntüleme üst verisinipackages/ai-core/src/providers.tsiçinde yansıtın. Katalog eşlik testi iki listeyi hizalı tutar. - Tauri komutu eklemek için →
src-tauri/src/*.rsiçinde bildirin,src-tauri/src/lib.rsiçinde kaydedin,src/lib/tauri.tsiçinde sarmalayın. - Belge motoru eklemek için →
DocumentEngine’isrc-tauri/src/document_engine.rsiç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.jsonbildirimi 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 servislerisrc/lib/ai-tools.tsiçindekiAiToolsHostü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).
Eşitleme ve GitHub iç yapısı
Bölüm başlığı “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
Bölüm başlığı “Kodlama stili”- TypeScript: var olanı izleyin. İstenmedikçe yorum eklemeyin.
noUnusedLocals/noUnusedParameterskurallarına uyun. - Rust: deyimsel yazın; küçük komutlar, anlaşılır hata iletileri.
- Arayüz: Tailwind v4 + Geist belirteçleri.
Button,TooltipveSelecttemel bileşenlerini yeniden kullanın.
Yayımlama
Bölüm başlığı “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 ve kullanıcı kurulumu.