डेवलपमेंट
Oleafly डेस्कटॉप रिपॉज़िटरी सेट करें, उसके पिन किए हुए साइडकार फ़ेच करें, ऐप चलाएँ, और मुख्य एक्सटेंशन पॉइंट समझें।
Oleafly एक Tauri 2 (नए टैब में खुलता है) डेस्कटॉप ऐप है। इसका React और TypeScript फ्रंटएंड Tauri IPC के ज़रिए Rust से बात करता है। Rust प्रोजेक्ट फ़ाइलों, कंपाइलेशन, सीक्रेट्स, MCP रूटिंग और AI प्रोवाइडर रिक्वेस्ट का मालिक है।
रिपॉज़िटरी लेआउट
“रिपॉज़िटरी लेआउट” शीर्षक वाला अनुभाग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/फ्रंटएंड एक pnpm वर्कस्पेस है। पुनः प्रयोग योग्य फीचर packages/* में इंजेक्ट किए गए पोर्ट के पीछे रहते हैं, और ऐप शेल उन्हें आपस में जोड़ता है। packages/ को छूने से पहले फ्रंटएंड आर्किटेक्चर पढ़ें: वह पोर्ट पैटर्न, कंट्रीब्यूशन रजिस्ट्री और एलाइज़ वायरिंग कवर करता है।
पूर्व आवश्यकताएँ
“पूर्व आवश्यकताएँ” शीर्षक वाला अनुभाग- Node.js 22.13+ और pnpm 11.9+ (सटीक pnpm वर्शन
package.jsonमें घोषित है) - rustup (नए टैब में खुलता है) से Rust (stable)
- आपके OS के लिए Tauri 2 सिस्टम डिपेंडेंसीज़ (नए टैब में खुलता है)
- सेटअप के दौरान वैकल्पिक: Markdown PDF कंपाइलेशन और डॉक्यूमेंट एक्सपोर्ट के लिए pandoc (नए टैब में खुलता है) (ऐप माँग पर अपना पिन किया हुआ बिल्ड इंस्टॉल कर सकता है)
पहला रन
“पहला रन” शीर्षक वाला अनुभागpnpm install./scripts/fetch-tectonic.sh all./scripts/fetch-biber.sh all./scripts/fetch-typst.sh allpnpm language-servers:fetchpnpm tauri devकिसी एक प्लेटफ़ॉर्म के लिए, हर शेल फ़ेच स्क्रिप्ट में उसका Rust टार्गेट ट्रिपल पास करें। होस्ट ट्रिपल जानने के लिए rustc -vV चलाएँ। जब तक आप कोई टार्गेट उसकी अंदरूनी स्क्रिप्ट के ज़रिए पास न करें, language-server कमांड मौजूदा होस्ट चुनता है।
रोज़मर्रा का काम
“रोज़मर्रा का काम” शीर्षक वाला अनुभाग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 खोलने से पहले की जाँचें
“PR खोलने से पहले की जाँचें” शीर्षक वाला अनुभागपुल रिक्वेस्ट खोलने से पहले संबंधित लोकल जाँचें चलाएँ:
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 sourcesदोनों ऑडिट कमांड को रजिस्ट्री/नेटवर्क एक्सेस चाहिए। CI हर कोड बदलाव पर उनके मौजूदा नतीजे रिकॉर्ड करता है। ऑफ़लाइन लोकल रन यह प्रमाणित नहीं कर सकता कि डिपेंडेंसी ग्राफ़ advisory-free है।
यूज़र को दिखने वाले बदलावों के लिए, असली ऐप और कंपाइलर के साथ एंड-टू-एंड सूट भी चलाएँ। e2e/README.md (नए टैब में खुलता है) देखें।
pnpm test:e2e:app # builds + launches the app, runs Playwright, tears downकंपाइल कैसे काम करता है
“कंपाइल कैसे काम करता है” शीर्षक वाला अनुभाग- फ्रंटएंड बैकएंड का
project_engineडिस्क्रिप्टर और उसके कैपबिलिटी फ़्लैग लोड करता है, फिर Tauri IPC के ज़रिएcompileProject(projectId, mainDoc, offline)कॉल करता है। - Rust
DocumentEngineके ज़रिए डिस्पैच करता है। UI कोड को फ़ाइल नाम से इंजन व्यवहार का अनुमान नहीं लगाना चाहिए। - LaTeX डिफ़ॉल्ट रूप से बंडल किए हुए Tectonic का उपयोग करता है। कोई प्रोजेक्ट इसके बजाय
latexmkके ज़रिए pdfLaTeX, XeLaTeX या LuaLaTeX चुन सकता है। पूरी सिस्टम TeX इंस्टॉलेशन को Oleafly के मैनेज्ड TinyTeX पर प्राथमिकता मिलती है। साझा डिटेक्टर यह प्राथमिकता देने से पहले कोर कंपाइलर,latexmk,kpsewhichऔर Biber माँगता है। - Typst वही सटीक वर्शन चलाता है जो प्रोजेक्ट
project.jsonमें पिन करता है: बंडल किया हुआ साइडकार, checksum-सत्यापित डाउनलोड, या वह सिस्टमtypstजो वह वर्शन बताता है। यह चुने हुए.typमुख्य डॉक्यूमेंट को मानव-पठनीय डायग्नोस्टिक्स और स्पष्ट PDF आउटपुट पाथ के साथ कंपाइल करता है। Auto compile चालू होने पर Rust इसके बजाय हर प्रोजेक्ट के लिए एकtypst watchप्रोसेस रखता है (src-tauri/src/typst_watch.rs)। डेस्कटॉप रिपॉज़िटरी काdocs/typst-toolchain.mdरिज़ॉल्यूशन, पिन और मैचिंग Tinymist कवर करता है। - Markdown, Pandoc को सीधे
.md/.markdownपर चलाता है, एक स्पष्ट आउटपुट पाथ और--pdf-engine=<absolute bundled Tectonic path>के साथ। Pandoc का मैनुअल पूरे PDF-इंजन पाथ का स्पष्ट समर्थन करता है। इसे अंतर्निहित सिस्टमpdflatexसे न बदलें, क्योंकि पैकेज्ड Oleafly किसी अघोषित TeX इंस्टॉलेशन पर निर्भर नहीं होना चाहिए। प्रोसेस प्रोजेक्ट रूट को अपनी वर्किंग डायरेक्टरी बनाकर चलती है ताकि सापेक्ष इमेज, बिबिलियोग्राफ़ी फ़ाइलें और CSL फ़ाइलें रूट और नेस्टेड दोनों मुख्य डॉक्यूमेंट के लिए काम करें।
Tauri का साइडकार दस्तावेज़ (नए टैब में खुलता है) टार्गेट-ट्रिपल सफ़िक्स वाले bundle.externalBin इनपुट परिभाषित करता है और रनटाइम पर पैकेज्ड साइडकार को उसके बिना-सफ़िक्स नाम से उपलब्ध कराता है। Oleafly का Pandoc एडाप्टर उस पैकेज्ड Tectonic एग्ज़ीक्यूटेबल को ऐप्लिकेशन एग्ज़ीक्यूटेबल के पास रिज़ॉल्व करता है, जो Tauri के डेस्कटॉप बंडल लेआउट से मेल खाता है। यूनिट टेस्ट macOS ऐप-बंडल और Cargo debug/release कैंडिडेट कवर करते हैं, जबकि रिलीज़ वर्कफ़्लो हर टार्गेट पर स्टेज किए हुए बिना-सफ़िक्स सिबलिंग की जाँच करता है।
Tectonic, Biber, Typst और language-server डाउनलोड वर्शनयुक्त और checksum-पिन होते हैं। उनकी फ़ेच स्क्रिप्ट आर्काइव संरचना की जाँच करती हैं और केवल समीक्षित एग्ज़ीक्यूटेबल या रिसोर्स पाथ ही निकालती हैं। CI और रिलीज़ बिल्ड एक ही स्क्रिप्ट उपयोग करते हैं।
- सभी इंजन नॉर्मलाइज़्ड लॉग/एरर इवेंट स्ट्रीम करते हैं। Rust कंपाइल मेटाडेटा JSON IPC से लौटाता है। PDF खुद अलग से रॉ बाइनरी IPC के रूप में फ़ेच होता है, नतीजे में base64 के रूप में एम्बेड नहीं होता।
- फ्रंटएंड PDF बाइट्स pdf.js से रेंडर करता है और नॉर्मलाइज़्ड डायग्नोस्टिक्स CodeMirror पर प्रकाशित करता है।
इंजन डिस्क्रिप्टर कंपाइलेशन पॉलिसी के साथ-साथ फ़ॉर्मैटिंग/सोर्स-प्रीफ़्लाइट प्रोफ़ाइल और फ़ीचर/एक्सपोर्ट/टेम्पलेट-काइंड सेट मॉडल करते हैं। फ्रंटएंड उपभोक्ता एक्सटेंशन से अनुमान लगाने के बजाय fail-closed files-store डिस्क्रिप्टर उपयोग करते हैं। डॉक्यूमेंट इंजन मैट्रिक्स (नए टैब में खुलता है) देखें।
Typst supports_synctex=true और supports_offline=true बताता है, साथ में supports_isolated_compile=false। सोर्स और PDF सिंक प्रोजेक्ट के मैच किए हुए Tinymist से चलता है और उसे Tinymist 0.13.30 या बाद का वर्शन चाहिए, इसलिए typst_toolchain::describe_project Typst 0.11 या 0.12 पर पिन किए हुए प्रोजेक्ट के लिए supports_synctex को false कर देता है (typst_sync::supported_for_project)। ऑफ़लाइन मोड Typst पैकेज डाउनलोड रोकता है, तब कंपाइल केवल साझा पैकेज कैश और प्रोजेक्ट के typst-packages फ़ोल्डर का उपयोग करता है। आइसोलेटेड कंपाइलेशन केवल LaTeX तक सीमित रहता है: TikZ फ़िगर पाथ Typst प्रोजेक्ट ठुकरा देता है, और असिस्टेंट के फ़िगर टूल Typst स्निपेट, जैसे कोई CeTZ कैनवास या fletcher डायग्राम, इसके बजाय render_typst_snippet से रेंडर करते हैं। इंजन व्यवहार केवल तब जोड़ें जब बैकएंड कैपबिलिटी सच्ची हो जाए। एक्सटेंशन आधारित UI अपवाद न जोड़ें।
स्टेट कहाँ रहता है
“स्टेट कहाँ रहता है” शीर्षक वाला अनुभाग- कॉन्फ़िग:
~/.oleafly/config.json(Unix पर0600)। ग़ैर-सीक्रेट प्राथमिकताएँ यहीं रहती हैं। - सीक्रेट्स:
~/.oleafly/ai-secrets.jsonऔर~/.oleafly/app-secrets.json, केवल-मालिक~/.oleafly/ai-secrets.keyसे एन्क्रिप्टेड। GitHub और MCPapp-secrets.jsonसाझा करते हैं। AI प्रोवाइडर क्रेडेंशियलai-secrets.jsonउपयोग करते हैं। - प्रोजेक्ट:
~/.oleafly/projects/<id>/,.gitवाले सादे फ़ोल्डर। - ऐप लॉग:
~/.oleafly/app.log।
मुख्य एक्सटेंशन पॉइंट
“मुख्य एक्सटेंशन पॉइंट” शीर्षक वाला अनुभाग- AI प्रोवाइडर जोड़ें →
crates/oleafly-agent/src/provider.rsअपडेट करें, फिर उसका डिस्प्ले मेटाडेटाpackages/ai-core/src/providers.tsमें दर्पण रूप में रखें। कैटलॉग समानता टेस्ट दोनों सूचियों को एकरेख रखता है। - Tauri कमांड जोड़ें →
src-tauri/src/*.rsमें घोषित करें,src-tauri/src/lib.rsमें रजिस्टर करें,src/lib/tauri.tsमें रैप करें। - डॉक्यूमेंट इंजन जोड़ें →
src-tauri/src/document_engine.rsमेंDocumentEngineलागू करें, सच्ची कैपबिलिटीज़ बताएँ, checksum-पिन साइडकार fetch/smoke पाथ जोड़ें, फिर UI कंट्रोल में डिस्क्रिप्टर उपयोग करें। - प्रोजेक्ट टेम्पलेट जोड़ें →
template.jsonमैनिफ़ेस्ट वाला फ़ोल्डरsrc-tauri/resources/templates/में डालें (इंजन-सामान्य टेम्पलेट मेटाडेटा अभी नियोजित काम है)। - AI के लिए टूल जोड़ें →
packages/ai-tools/src/tools.ts। जो ऐप सर्विसेज़ इसे चाहिए वेsrc/lib/ai-tools.tsकेAiToolsHostसे जाएँ। - रेल टैब / पैलेट या ऑम्निबार कमांड / AI टूलसेट जोड़ें → इसे
src/contributions/में रजिस्टर करें (फ्रंटएंड आर्किटेक्चर देखें)।
सिंक और GitHub इंटरनल्स
“सिंक और GitHub इंटरनल्स” शीर्षक वाला अनुभागOAuth डिवाइस फ़्लो Rust में सर्वर-साइड चलता है (src-tauri/src/github.rs) क्योंकि OAuth एंडपॉइंट CORS-सक्षम नहीं हैं। API कॉल (api.github.com) फ्रंटएंड से होते हैं।
कोडिंग स्टाइल
“कोडिंग स्टाइल” शीर्षक वाला अनुभाग- TypeScript: जो पहले से है उसी का पालन करें। माँगे बिना कोई कमेंट नहीं।
noUnusedLocals/noUnusedParametersका पालन करें। - Rust: इडियोमैटिक, छोटे कमांड, मित्रतापूर्ण एरर स्ट्रिंग।
- UI: Tailwind v4 + Geist टोकन।
Button,TooltipऔरSelectप्रिमिटिव पुनः उपयोग करें।
रिलीज़ करना
“रिलीज़ करना” शीर्षक वाला अनुभागपैकेजिंग macOS Apple Silicon, Windows x64, Linux x64 और Linux ARM64 को टार्गेट करती है। हर बिल्ड अपने कंपाइलर साइडकार और बंडल किए हुए language-server रिसोर्स फ़ेच करके जाँचता है। रिलीज़ बिल्ड macOS पर Apple साइनिंग और नोटराइज़ेशन, और Windows पर Azure Artifact Signing सपोर्ट करते हैं। रिलीज़ करना और यूज़र इंस्टॉल देखें।