# डेवलपमेंट

Oleafly डेस्कटॉप रिपॉज़िटरी सेट करें, उसके पिन किए हुए साइडकार फ़ेच करें, ऐप चलाएँ, और मुख्य एक्सटेंशन पॉइंट समझें।

Oleafly एक [Tauri 2](https://tauri.app) डेस्कटॉप ऐप है। इसका 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/` को छूने से पहले [फ्रंटएंड आर्किटेक्चर](/docs/engineering/architecture/) पढ़ें: वह पोर्ट पैटर्न, कंट्रीब्यूशन रजिस्ट्री और एलाइज़ वायरिंग कवर करता है।

## पूर्व आवश्यकताएँ

- Node.js 22.13+ और pnpm 11.9+ (सटीक pnpm वर्शन `package.json` में घोषित है)
- [rustup](https://rustup.rs) से Rust (stable)
- आपके OS के लिए [Tauri 2 सिस्टम डिपेंडेंसीज़](https://v2.tauri.app/start/prerequisites/)
- सेटअप के दौरान वैकल्पिक: Markdown PDF कंपाइलेशन और डॉक्यूमेंट एक्सपोर्ट के लिए [pandoc](https://pandoc.org/installing.html) (ऐप माँग पर अपना पिन किया हुआ बिल्ड इंस्टॉल कर सकता है)

## पहला रन

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

किसी एक प्लेटफ़ॉर्म के लिए, हर शेल फ़ेच स्क्रिप्ट में उसका Rust टार्गेट ट्रिपल पास करें। होस्ट ट्रिपल जानने के लिए `rustc -vV` चलाएँ। जब तक आप कोई टार्गेट उसकी अंदरूनी स्क्रिप्ट के ज़रिए पास न करें, language-server कमांड मौजूदा होस्ट चुनता है।

## रोज़मर्रा का काम

```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 खोलने से पहले की जाँचें

पुल रिक्वेस्ट खोलने से पहले संबंधित लोकल जाँचें चलाएँ:

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

दोनों ऑडिट कमांड को रजिस्ट्री/नेटवर्क एक्सेस चाहिए। CI हर कोड बदलाव पर उनके मौजूदा नतीजे रिकॉर्ड करता है। ऑफ़लाइन लोकल रन यह प्रमाणित नहीं कर सकता कि डिपेंडेंसी ग्राफ़ advisory-free है।

यूज़र को दिखने वाले बदलावों के लिए, असली ऐप और कंपाइलर के साथ एंड-टू-एंड सूट भी चलाएँ। [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
```

## कंपाइल कैसे काम करता है

1. फ्रंटएंड बैकएंड का `project_engine` डिस्क्रिप्टर और उसके कैपबिलिटी फ़्लैग लोड करता है, फिर Tauri IPC के ज़रिए `compileProject(projectId, mainDoc, offline)` कॉल करता है।
2. Rust `DocumentEngine` के ज़रिए डिस्पैच करता है। UI कोड को फ़ाइल नाम से इंजन व्यवहार का अनुमान नहीं लगाना चाहिए।
3. LaTeX डिफ़ॉल्ट रूप से बंडल किए हुए Tectonic का उपयोग करता है। कोई प्रोजेक्ट इसके बजाय `latexmk` के ज़रिए pdfLaTeX, XeLaTeX या LuaLaTeX चुन सकता है। पूरी सिस्टम TeX इंस्टॉलेशन को Oleafly के मैनेज्ड TinyTeX पर प्राथमिकता मिलती है। साझा डिटेक्टर यह प्राथमिकता देने से पहले कोर कंपाइलर, `latexmk`, `kpsewhich` और Biber माँगता है।
4. Typst वही सटीक वर्शन चलाता है जो प्रोजेक्ट `project.json` में पिन करता है: बंडल किया हुआ साइडकार, checksum-सत्यापित डाउनलोड, या वह सिस्टम `typst` जो वह वर्शन बताता है। यह चुने हुए `.typ` मुख्य डॉक्यूमेंट को मानव-पठनीय डायग्नोस्टिक्स और स्पष्ट PDF आउटपुट पाथ के साथ कंपाइल करता है। Auto compile चालू होने पर Rust इसके बजाय हर प्रोजेक्ट के लिए एक `typst watch` प्रोसेस रखता है (`src-tauri/src/typst_watch.rs`)। डेस्कटॉप रिपॉज़िटरी का `docs/typst-toolchain.md` रिज़ॉल्यूशन, पिन और मैचिंग Tinymist कवर करता है।
5. Markdown, Pandoc को सीधे `.md`/`.markdown` पर चलाता है, एक स्पष्ट आउटपुट पाथ और `--pdf-engine=<absolute bundled Tectonic path>` के साथ। Pandoc का मैनुअल पूरे PDF-इंजन पाथ का स्पष्ट समर्थन करता है। इसे अंतर्निहित सिस्टम `pdflatex` से न बदलें, क्योंकि पैकेज्ड Oleafly किसी अघोषित TeX इंस्टॉलेशन पर निर्भर नहीं होना चाहिए। प्रोसेस प्रोजेक्ट रूट को अपनी वर्किंग डायरेक्टरी बनाकर चलती है ताकि सापेक्ष इमेज, बिबिलियोग्राफ़ी फ़ाइलें और CSL फ़ाइलें रूट और नेस्टेड दोनों मुख्य डॉक्यूमेंट के लिए काम करें।

Tauri का [साइडकार दस्तावेज़](https://v2.tauri.app/develop/sidecar/) टार्गेट-ट्रिपल सफ़िक्स वाले `bundle.externalBin` इनपुट परिभाषित करता है और रनटाइम पर पैकेज्ड साइडकार को उसके बिना-सफ़िक्स नाम से उपलब्ध कराता है। Oleafly का Pandoc एडाप्टर उस पैकेज्ड Tectonic एग्ज़ीक्यूटेबल को ऐप्लिकेशन एग्ज़ीक्यूटेबल के पास रिज़ॉल्व करता है, जो Tauri के डेस्कटॉप बंडल लेआउट से मेल खाता है। यूनिट टेस्ट macOS ऐप-बंडल और Cargo debug/release कैंडिडेट कवर करते हैं, जबकि रिलीज़ वर्कफ़्लो हर टार्गेट पर स्टेज किए हुए बिना-सफ़िक्स सिबलिंग की जाँच करता है।

Tectonic, Biber, Typst और language-server डाउनलोड वर्शनयुक्त और checksum-पिन होते हैं। उनकी फ़ेच स्क्रिप्ट आर्काइव संरचना की जाँच करती हैं और केवल समीक्षित एग्ज़ीक्यूटेबल या रिसोर्स पाथ ही निकालती हैं। CI और रिलीज़ बिल्ड एक ही स्क्रिप्ट उपयोग करते हैं।

6. सभी इंजन नॉर्मलाइज़्ड लॉग/एरर इवेंट स्ट्रीम करते हैं। Rust कंपाइल मेटाडेटा JSON IPC से लौटाता है। PDF खुद अलग से रॉ बाइनरी IPC के रूप में फ़ेच होता है, नतीजे में base64 के रूप में एम्बेड नहीं होता।
7. फ्रंटएंड PDF बाइट्स pdf.js से रेंडर करता है और नॉर्मलाइज़्ड डायग्नोस्टिक्स CodeMirror पर प्रकाशित करता है।

इंजन डिस्क्रिप्टर कंपाइलेशन पॉलिसी के साथ-साथ फ़ॉर्मैटिंग/सोर्स-प्रीफ़्लाइट प्रोफ़ाइल और फ़ीचर/एक्सपोर्ट/टेम्पलेट-काइंड सेट मॉडल करते हैं। फ्रंटएंड उपभोक्ता एक्सटेंशन से अनुमान लगाने के बजाय fail-closed files-store डिस्क्रिप्टर उपयोग करते हैं। [डॉक्यूमेंट इंजन मैट्रिक्स](https://github.com/Oleafly/Oleafly/blob/main/docs/document-engines.md) देखें।

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 और MCP `app-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/` में रजिस्टर करें ([फ्रंटएंड आर्किटेक्चर](/docs/engineering/architecture/#the-contribution-registry) देखें)।

## सिंक और 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 सपोर्ट करते हैं। [रिलीज़ करना](/docs/engineering/releasing/) और यूज़र [इंस्टॉल](/docs/install/) देखें।
