# Розробка

Налаштуйте репозиторій настільного застосунку Oleafly, завантажте його закріплені sidecar-бінарники, запустіть застосунок і зрозумійте головні точки розширення.

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 (stable) через [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
```

### Перевірки перед відкриттям pull request

Запустіть відповідні локальні перевірки перед відкриттям pull request:

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

Для змін, видимих користувачам, також запустіть наскрізний набір тестів проти справжнього застосунку й компілятора. Див. [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 має пріоритет над керованим Oleafly TinyTeX. Спільний детектор вимагає наявності основних компіляторів, `latexmk`, `kpsewhich` і Biber, перш ніж надати цей пріоритет.
4. Typst запускає точно ту версію, яку проєкт закріпив у `project.json`: вбудований sidecar, завантаження з перевіреною контрольною сумою або системний `typst`, що повідомляє цю версію. Він компілює обраний головний документ `.typ` зі зрозумілими людині діагностичними повідомленнями та явним шляхом виводу PDF. Коли увімкнена автокомпіляція, Rust натомість тримає один процес `typst watch` на проєкт (`src-tauri/src/typst_watch.rs`). Розв’язання версій, закріплення та відповідний Tinymist описано в `docs/typst-toolchain.md` репозиторію настільного застосунку.
5. Markdown викликає Pandoc безпосередньо для `.md`/`.markdown` з явним
   шляхом виводу та `--pdf-engine=<absolute bundled Tectonic path>`. Керівництво
   Pandoc прямо підтримує повний шлях до рушія PDF. Не замінюйте його неявним
   системним `pdflatex`, бо упакований Oleafly не повинен залежати від
   необ’явленої установки TeX. Процес запускається з коренем проєкту
   як робочим каталогом, тож відносні зображення, файли бібліографії
   та файли CSL працюють і для кореневих, і для вкладених
   головних документів.

[Документація Tauri щодо sidecar](https://v2.tauri.app/develop/sidecar/) визначає входи `bundle.externalBin` із суфіксами цільових триплетів і відкриває упакований sidecar під іменем без суфікса під час виконання. Адаптер Pandoc в Oleafly знаходить цей упакований виконуваний файл Tectonic поруч із виконуваним файлом застосунку, що відповідає структурі настільного пакета Tauri. Модульні тести охоплюють кандидати app-bundle macOS і debug/release Cargo, а робочий процес випуску перевіряє підготовлений сусідній файл без суфікса на кожній цільовій платформі.

Завантаження Tectonic, Biber, Typst і мовних серверів версіоновані та закріплені контрольними сумами. Їхні скрипти завантаження перевіряють структуру архіву й розпаковують лише переглянуті шляхи виконуваних файлів і ресурсів. CI і збірки релізу використовують ті самі скрипти.

6. Усі рушії передають потоком нормалізовані події журналу й помилок. Rust повертає метадані компіляції через JSON IPC. Сам PDF отримується окремо як сирі двійкові дані через IPC, а не вбудовується в результат як base64.
7. Фронтенд відтворює байти PDF за допомогою pdf.js і передає нормалізовану діагностику до CodeMirror.

Дескриптори рушіїв моделюють політику компіляції, а також профілі форматування й передперевірки джерела та набори можливостей, експорту й видів шаблонів. Споживачі на фронтенді використовують дескриптор сховища файлів у режимі fail-closed, а не вгадують за розширеннями. Див. [матрицю рушіїв документів](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`, відкрийте правдиві можливості, додайте закріплений контрольними сумами шлях завантаження й перевірки sidecar, потім споживайте дескриптор у елементах керування інтерфейсу.
- Додати шаблон проєкту → покладіть теку з маніфестом `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 (api.github.com) відбуваються з фронтенду.

## Стиль коду

- TypeScript: дотримуйтеся того, що вже є. Без коментарів, якщо не просять. Поважайте `noUnusedLocals`/`noUnusedParameters`.
- Rust: ідіоматично, невеликі команди, доброзичливі рядки помилок.
- UI: Tailwind v4 + токени Geist. Повторно використовуйте примітиви `Button`, `Tooltip` і `Select`.

## Випуск

Пакування орієнтується на macOS Apple Silicon, Windows x64, Linux x64 і Linux ARM64. Кожна збірка завантажує й перевіряє свої sidecar-компілятори та вбудований ресурс мовних серверів. Релізні збірки підтримують підписування й нотаризацію Apple на macOS та Azure Artifact Signing на Windows. Див. [випуск релізів](/docs/engineering/releasing/) та [встановлення](/docs/install/) для користувачів.
