# Phát triển

Thiết lập kho mã desktop Oleafly, tải các sidecar đã ghim phiên bản, chạy ứng dụng và hiểu các điểm mở rộng chính.

Oleafly là một ứng dụng desktop [Tauri 2](https://tauri.app). Phần frontend viết bằng React và TypeScript giao tiếp với Rust qua Tauri IPC. Rust quản lý tệp dự án, biên dịch, thông tin mật, định tuyến MCP và các yêu cầu tới nhà cung cấp AI.

## Bố cục kho mã

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

Phần frontend là một pnpm workspace. Các tính năng dùng lại được nằm trong `packages/*` đằng sau các port được tiêm vào, và app shell nối chúng lại với nhau. Hãy đọc [Kiến trúc frontend](/docs/engineering/architecture/) trước khi đụng vào `packages/`: bài viết đó trình bày mẫu hình port, contribution registry và cách nối alias.

## Yêu cầu trước

- Node.js 22.13+ và pnpm 11.9+ (phiên bản pnpm chính xác được khai báo trong `package.json`)
- Rust (bản stable) cài qua [rustup](https://rustup.rs)
- Các [phụ thuộc hệ thống của Tauri 2](https://v2.tauri.app/start/prerequisites/) cho hệ điều hành của bạn
- Tùy chọn khi cài đặt: [pandoc](https://pandoc.org/installing.html) để biên dịch PDF từ Markdown và xuất tài liệu (ứng dụng có thể cài bản đã ghim khi cần)

## Chạy lần đầu

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

Đối với một nền tảng duy nhất, hãy truyền Rust target triple của nền tảng đó vào từng script fetch dạng shell. Dùng `rustc -vV` để tìm host triple. Lệnh language-server chọn host hiện tại trừ khi bạn truyền target qua script bên dưới của nó.

## Công việc hằng ngày

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

### Các kiểm tra trước khi mở PR

Chạy các kiểm tra cục bộ liên quan trước khi mở 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
```

Hai lệnh audit cần truy cập registry/mạng. CI ghi lại kết quả hiện tại của chúng ở mỗi thay đổi mã. Một lần chạy cục bộ ngoại tuyến không thể chứng nhận rằng đồ thị phụ thuộc không chứa advisory nào.

Với các thay đổi hướng tới người dùng, hãy chạy thêm bộ kiểm thử end-to-end trên ứng dụng và trình biên dịch thật. Xem [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
```

## Một lần biên dịch hoạt động như thế nào

1. Frontend tải descriptor `project_engine` từ backend cùng các cờ capability của nó, rồi gọi `compileProject(projectId, mainDoc, offline)` qua Tauri IPC.
2. Rust điều phối qua `DocumentEngine`. Code UI không được suy đoán hành vi engine từ tên tệp.
3. LaTeX dùng Tectonic đi kèm theo mặc định. Một dự án có thể thay vào đó chọn pdfLaTeX, XeLaTeX hoặc LuaLaTeX qua `latexmk`. Một bản cài TeX hệ thống hoàn chỉnh được ưu tiên hơn TinyTeX do Oleafly quản lý. Bộ dò chung yêu cầu có các trình biên dịch lõi, `latexmk`, `kpsewhich` và Biber trước khi trao quyền ưu tiên đó.
4. Typst chạy đúng phiên bản mà dự án ghim trong `project.json`: sidecar đi kèm, một bản tải về được kiểm tra checksum, hoặc một `typst` hệ thống báo đúng phiên bản đó. Nó biên dịch tệp chính `.typ` được chọn với các chẩn đoán dễ đọc và một đường dẫn xuất PDF tường minh. Khi Auto compile bật, Rust thay vào đó giữ một tiến trình `typst watch` cho mỗi dự án (`src-tauri/src/typst_watch.rs`). Tài liệu `docs/typst-toolchain.md` của kho desktop trình bày việc phân giải, ghim phiên bản và Tinymist tương ứng.
5. Markdown gọi Pandoc trực tiếp trên `.md`/`.markdown`, với một đường dẫn xuất tường minh và
   `--pdf-engine=<absolute bundled Tectonic path>`. Tài liệu hướng dẫn của Pandoc
   hỗ trợ tường minh một đường dẫn PDF-engine đầy đủ. Đừng thay thế điều này bằng một
   `pdflatex` hệ thống ngầm định, vì bản đóng gói của Oleafly không được phụ thuộc vào một
   bản cài TeX không được khai báo. Tiến trình chạy với thư mục gốc của dự án làm thư mục
   làm việc, nên các ảnh dùng đường dẫn tương đối, tệp tài liệu tham khảo và tệp CSL đều
   hoạt động cho cả tài liệu chính ở gốc lẫn tài liệu chính nằm lồng trong.

Tài liệu [sidecar của Tauri](https://v2.tauri.app/develop/sidecar/) định nghĩa các đầu vào
`bundle.externalBin` với hậu tố target-triple và đưa sidecar đã đóng gói ra dưới tên không
hậu tố khi chạy. Adapter Pandoc của Oleafly phân giải tệp thực thi Tectonic đã đóng gói nằm
cạnh tệp thực thi của ứng dụng, đúng với bố cục bundle desktop của Tauri. Unit test bao phủ
các ứng viên app-bundle macOS và debug/release của Cargo, trong khi workflow phát hành kiểm
tra tệp anh em không hậu tố đã dựng ở mọi target.

Các bản tải Tectonic, Biber, Typst và language-server đều được đánh phiên bản và ghim
checksum. Các script fetch của chúng kiểm tra tính hợp lệ của cấu trúc archive và chỉ giải
nén các đường dẫn tệp thực thi hay tài nguyên đã được soát. CI và các bản build phát hành
dùng chính các script đó.

6. Mọi engine đều phát trực tuyến các sự kiện log/lỗi đã chuẩn hóa. Rust trả về metadata biên dịch qua JSON IPC. Bản thân tệp PDF được lấy riêng qua IPC nhị phân thô thay vì nhúng dạng base64 trong kết quả.
7. Frontend dựng các byte PDF bằng pdf.js và công bố các chẩn đoán đã chuẩn hóa lên CodeMirror.

Descriptor của engine mô hình hóa chính sách biên dịch cùng các profile định dạng/source-preflight
và các tập hợp tính năng/xuất/loại-mẫu. Các bên dùng ở frontend sử dụng descriptor fail-closed
từ files-store thay vì đoán theo phần mở rộng tệp. Xem
[ma trận document engine](https://github.com/Oleafly/Oleafly/blob/main/docs/document-engines.md).

Typst báo `supports_synctex=true` và `supports_offline=true`, cùng
`supports_isolated_compile=false`. Đồng bộ source và PDF chạy qua Tinymist khớp với dự án và
cần Tinymist 0.13.30 trở lên, nên `typst_toolchain::describe_project` hạ `supports_synctex`
xuống `false` cho dự án ghim Typst 0.11 hoặc 0.12 (`typst_sync::supported_for_project`).
Chế độ Offline chặn việc tải gói Typst, nên khi đó một lần biên dịch chỉ dùng bộ nhớ đệm gói
dùng chung và thư mục `typst-packages` của dự án. Biên dịch cô lập vẫn chỉ dành cho LaTeX:
đường vẽ hình TikZ từ chối dự án Typst, và các công cụ hình của trợ lý dựng các đoạn Typst,
chẳng hạn canvas CeTZ hay sơ đồ fletcher, bằng `render_typst_snippet` thay thế. Chỉ thêm hành
vi engine sau khi capability của backend trở nên trung thực. Đừng thêm ngoại lệ UI dựa trên
phần mở rộng tệp.

## Trạng thái nằm ở đâu

- Cấu hình: `~/.oleafly/config.json` (`0600` trên Unix). Các tùy chọn không chứa thông tin mật nằm ở đây.
- Thông tin mật: `~/.oleafly/ai-secrets.json` và `~/.oleafly/app-secrets.json`, được mã hóa bằng `~/.oleafly/ai-secrets.key` chỉ chủ sở hữu mới dùng được. GitHub và MCP dùng chung `app-secrets.json`. Thông tin đăng nhập của nhà cung cấp AI dùng `ai-secrets.json`.
- Dự án: `~/.oleafly/projects/<id>/`, là các thư mục thường kèm `.git`.
- Nhật ký ứng dụng: `~/.oleafly/app.log`.

## Các điểm mở rộng chính

- Thêm một nhà cung cấp AI → cập nhật `crates/oleafly-agent/src/provider.rs`, rồi phản chiếu metadata hiển thị của nó trong `packages/ai-core/src/providers.ts`. Test đối chiếu catalog giữ cho hai danh sách khớp nhau.
- Thêm một lệnh Tauri → khai báo trong `src-tauri/src/*.rs`, đăng ký trong `src-tauri/src/lib.rs`, bọc trong `src/lib/tauri.ts`.
- Thêm một document engine → hiện thực `DocumentEngine` trong `src-tauri/src/document_engine.rs`, công bố các capability trung thực, thêm đường fetch/smoke cho sidecar được ghim checksum, rồi dùng descriptor trong các điều khiển UI.
- Thêm một mẫu dự án → thả một thư mục kèm manifest `template.json` vào `src-tauri/resources/templates/` (metadata mẫu chung cho mọi engine vẫn là việc đã lên kế hoạch).
- Thêm một công cụ cho AI → `packages/ai-tools/src/tools.ts`. Các dịch vụ ứng dụng mà nó cần đi qua `AiToolsHost` trong `src/lib/ai-tools.ts`.
- Thêm một thẻ rail / lệnh palette hoặc omnibar / bộ công cụ AI → đăng ký trong `src/contributions/` (xem [Kiến trúc frontend](/docs/engineering/architecture/#the-contribution-registry)).

## Bên trong đồng bộ và GitHub

OAuth device flow chạy phía server bằng Rust (`src-tauri/src/github.rs`) vì các endpoint OAuth không bật CORS. Các lượt gọi API (api.github.com) diễn ra từ frontend.

## Phong cách viết mã

- TypeScript: theo những gì đã có sẵn. Không ghi chú giải trừ khi được yêu cầu. Tôn trọng `noUnusedLocals`/`noUnusedParameters`.
- Rust: idiomatic, lệnh nhỏ gọn, chuỗi lỗi thân thiện.
- UI: Tailwind v4 + token Geist. Tái sử dụng các primitive `Button`, `Tooltip` và `Select`.

## Phát hành

Đóng gói nhắm tới macOS Apple Silicon, Windows x64, Linux x64 và Linux ARM64. Mỗi bản build tải về và kiểm tra các sidecar trình biên dịch cùng tài nguyên language-server đi kèm. Các bản build phát hành hỗ trợ ký và notarization của Apple trên macOS và Azure Artifact Signing trên Windows. Xem
[phát hành](/docs/engineering/releasing/) và [cài đặt](/docs/install/) cho người dùng.
