# Разработка

Настройте репозиторий настольного приложения Oleafly, загрузите его закреплённые сайдкары, запустите приложение и разберитесь в основных точках расширения.

Oleafly — настольное приложение на [Tauri 2](https://tauri.app). Его фронтенд на React и TypeScript общается с Rust через IPC Tauri. 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/
```

Фронтенд — это workspace на 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
```

### Проверки перед открытием PR

Перед открытием 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 записывает их текущие
результаты при каждом изменении кода. Локальный запуск без сети не может
подтвердить, что граф зависимостей свободен от уязвимостей.

Для изменений, видимых пользователю, дополнительно запустите сквозной набор тестов на реальном приложении и компиляторе. См. [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)` через IPC Tauri.
2. Rust выполняет диспетчеризацию через `DocumentEngine`. Код интерфейса не должен делать выводов о поведении движка из имени файла.
3. LaTeX по умолчанию использует встроенный Tectonic. Вместо этого проект может выбрать pdfLaTeX, XeLaTeX или LuaLaTeX через `latexmk`. Полная системная установка TeX имеет приоритет над управляемым Oleafly TinyTeX. Общий детектор требует наличия основных компиляторов, `latexmk`, `kpsewhich` и Biber, прежде чем предоставить этот приоритет.
4. Typst запускает ровно ту версию, которую проект закрепил в `project.json`: встроенный сайдкар, загрузку с проверенной контрольной суммой или системный `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](https://v2.tauri.app/develop/sidecar/) определяет
входы `bundle.externalBin` с суффиксами целевых триплетов и открывает упакованный
сайдкар во время выполнения под именем без суффикса. Адаптер 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`, объявите правдивые возможности, добавьте путь загрузки сайдкара с закреплённой контрольной суммой и дымовой проверки, затем используйте дескриптор в элементах интерфейса.
- Добавить шаблон проекта → положите папку с манифестом `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: идиоматичный код, небольшие команды, понятные сообщения об ошибках.
- Интерфейс: 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/) для пользователей.
