# التطوير

أعد إعداد مستودع Oleafly لسطح المكتب، وجلب أدواته المرافقة المقيّدة الإصدار، وتشغيل التطبيق، وفهم نقاط الامتداد الرئيسية.

Oleafly تطبيق سطح مكتب مبني على [Tauri 2](https://tauri.app). تتواصل واجهته الأمامية المكتوبة بـReact وTypeScript مع Rust عبر Tauri IPC. وتتولى Rust ملفات المشروع والتجميع والأسرار وتوجيه MCP وطلبات مزوّدي الذكاء الاصطناعي.

## تخطيط المستودع

```
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/*` خلف منافذ محقونة، ويربط غلاف التطبيق بينها. اقرأ [بنية الواجهة الأمامية](/docs/engineering/architecture/) قبل تعديل `packages/`: فهي تغطي نمط المنافذ وسجل المساهمات وربط الأسماء المستعارة.

## المتطلبات المسبقة

- Node.js 22.13+ وpnpm 11.9+ (يُعلَن إصدار pnpm الدقيق في `package.json`)
- Rust (الإصدار المستقر) عبر [rustup](https://rustup.rs)
- [تبعيات نظام Tauri 2](https://v2.tauri.app/start/prerequisites/) لنظام التشغيل لديك
- اختياري أثناء الإعداد: [pandoc](https://pandoc.org/installing.html) لتجميع PDF من Markdown وتصدير المستندات (يستطيع التطبيق تثبيت نسخته المقيّدة الإصدار عند الطلب)

## التشغيل الأول

```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` لمعرفة ثلاثية المضيف. ويختار أمر خوادم اللغة المضيف الحالي ما لم تمرّر هدفًا عبر البرنامج النصي الأساسي له.

## العمل اليومي

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

### الفحوص قبل فتح طلب سحب

شغّل الفحوص المحلية ذات الصلة قبل فتح طلب سحب:

```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 نتائجهما الحالية عند كل تغيير في الشفرة. ولا يستطيع تشغيل محلي بلا اتصال أن يوثّق خلو مخطط التبعيات من التحذيرات الأمنية.

للتغييرات التي تظهر للمستخدم، شغّل أيضًا مجموعة الاختبارات الشاملة (end-to-end) مقابل التطبيق والمجمّع الحقيقيين. انظر [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` من الواجهة الخلفية وعلامات قدراته، ثم تستدعي `compileProject(projectId, mainDoc, offline)` عبر Tauri IPC.
2. توجّه Rust الطلب عبر `DocumentEngine`. لا يجوز لشفرة الواجهة أن تستنتج سلوك المحرك من اسم ملف.
3. يستخدم LaTeX نسخة Tectonic المدمجة افتراضيًا. ويستطيع المشروع بدلًا من ذلك اختيار pdfLaTeX أو XeLaTeX أو LuaLaTeX عبر `latexmk`. وتتقدّم تثبيتات TeX النظامية الكاملة على TinyTeX الذي يديره Oleafly. ويشترط الكاشف المشترك وجود المجمّعات الأساسية و`latexmk` و`kpsewhich` وBiber قبل منح تلك الأولوية.
4. يشغّل Typst الإصدار الذي يقيّده المشروع في `project.json` تحديدًا: الأداة المرافقة المدمجة، أو تنزيل يُتحقق من مجموعه الاختباري، أو أمر `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` بلواحق ثلاثية الهدف، وتعرض الأداة المرافقة المحزَّمة باسمها دون لاحقة وقت التشغيل. ويحلّ مهايئ Pandoc في Oleafly مسار تنفيذ Tectonic المحزَّم بجوار ملف تنفيذ التطبيق، بما يطابق تخطيط حزمة Tauri لسطح المكتب. وتغطي اختبارات الوحدة مرشحي حزمة تطبيق macOS ومرشحي debug وrelease لـCargo، بينما يفحص سير عمل الإصدار النسخة الشقيقة المُجهَّزة بلا لاحقة على كل هدف.

تنزيلات Tectonic وBiber وTypst وخوادم اللغة مُنسّقة ومقيّدة بالمجاميع الاختبارية. تتحقق برامج الجلب الخاصة بها من بنية الأرشيف ولا تستخرج إلا مسارات التنفيذ أو الموارد المراجَعة. وتستخدم CI وبنيات الإصدار البرامج النصية نفسها.

6. تبثّ جميع المحركات أحداث سجلات وأخطاء موحّدة. تعيد Rust بيانات التجميع الوصفية عبر IPC بصيغة JSON. ويُجلب ملف PDF نفسه على حدة عبر IPC ثنائي خام بدلًا من تضمينه بترميز base64 في النتيجة.
7. تعرض الواجهة الأمامية بايتات PDF باستخدام pdf.js وتنشر التشخيصات الموحّدة إلى CodeMirror.

تُعبّر واصفات المحركات عن سياسة التجميع، إضافة إلى ملفات تعريف التنسيق والفحص المسبق للمصدر ومجموعات الميزات والتصدير وأنواع القوالب. وتستخدمها الواجهة الأمامية عبر واصف مخزن الملفات المتوقف عند الفشل بدلًا من التخمين من الامتدادات. انظر [مصفوفة محركات المستندات](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` قيمة `supports_synctex` إلى `false` للمشروع المقيّد بـTypst 0.11 أو 0.12 (`typst_sync::supported_for_project`). ويحظر وضع عدم الاتصال تنزيل حزم Typst، فيستخدم التجميع حينها ذاكرة الحزم المشتركة ومجلد `typst-packages` الخاص بالمشروع فقط. ويبقى التجميع المعزول خاصًا بـLaTeX: يرفض مسار أشكال TikZ مشاريع Typst، وتعرض أدوات الأشكال في المساعد مقتطفات Typst، مثل لوحة CeTZ أو مخطط fletcher، عبر `render_typst_snippet` بدلًا من ذلك. أضف سلوك محرك فقط بعد أن تصبح قدرة الواجهة الخلفية صادقة. ولا تضف استثناءات واجهة قائمة على الامتدادات.

## أين تُخزَّن الحالة

- الإعدادات: `~/.oleafly/config.json` (بصلاحية `0600` على Unix). تعيش التفضيلات غير السرية هنا.
- الأسرار: `~/.oleafly/ai-secrets.json` و`~/.oleafly/app-secrets.json`، مشفّرة بالمفتاح `~/.oleafly/ai-secrets.key` الذي يخص المالك وحده. يتشارك GitHub وMCP في ملف `app-secrets.json`. وتستخدم بيانات اعتماد مزوّدي الذكاء الاصطناعي `ai-secrets.json`.
- المشاريع: `~/.oleafly/projects/<id>/`، مجلدات عادية تحتوي `.git`.
- سجل التطبيق: `~/.oleafly/app.log`.

## نقاط الامتداد الرئيسية

- إضافة مزوّد ذكاء اصطناعي ← حدّث `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`.
- إضافة محرك مستندات ← نفّذ `DocumentEngine` في `src-tauri/src/document_engine.rs`، واعرض قدرات صادقة، وأضف مسار جلب واختبار سريع لأداة مرافقة مقيّدة بمجموع اختباري، ثم استخدم الواصف في عناصر تحكم الواجهة.
- إضافة قالب مشروع ← ضع مجلدًا يحمل بيان `template.json` في `src-tauri/resources/templates/` (تبقى البيانات الوصفية للقوالب العامة عبر المحركات عملًا مخططًا له).
- إضافة أداة للذكاء الاصطناعي ← `packages/ai-tools/src/tools.ts`. وتمر خدمات التطبيق التي يحتاجها عبر `AiToolsHost` في `src/lib/ai-tools.ts`.
- إضافة علامة تبويب جانبية أو أمر لوحة أو شريط أوامر أو مجموعة أدوات ذكاء اصطناعي ← سجّلها في `src/contributions/` (انظر [بنية الواجهة الأمامية](/docs/engineering/architecture/#the-contribution-registry)).

## داخل المزامنة وGitHub

يجري تدفق أجهزة OAuth من جهة الخادم في Rust (`src-tauri/src/github.rs`) لأن نقاط نهاية OAuth لا تدعم CORS. أما استدعاءات الواجهة البرمجية (api.github.com) فتحدث من الواجهة الأمامية.

## أسلوب الشفرة

- TypeScript: اتبع الموجود بالفعل. لا تعليقات ما لم تُطلب. احترم `noUnusedLocals`/`noUnusedParameters`.
- Rust: أسلوب اصطلاحي، أوامر صغيرة، ورسائل خطأ ودّية.
- الواجهة: Tailwind v4 مع رموز Geist. أعد استخدام العناصر الأولية `Button` و`Tooltip` و`Select`.

## الإصدار

تستهدف الحزم macOS Apple Silicon وWindows x64 وLinux x64 وLinux ARM64. تجلب كل بنية أدواتها المرافقة للمجمّعات ومورد خوادم اللغة المدمج وتتحقق منها. وتدعم بنيات الإصدار توقيع Apple وتوثيقه على macOS وتوقيع Azure Artifact Signing على Windows. انظر [الإصدار](/docs/engineering/releasing/) و[التثبيت](/docs/install/) للمستخدم.
