# 개발

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`로 확인합니다. 언어 서버 명령은 하위 스크립트에 타깃을 넘기지 않으면 현재 호스트를 선택합니다.

## 일상 작업

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

두 audit 명령은 레지스트리와 네트워크 접근이 필요합니다. 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` 디스크립터와 기능 플래그를 불러온 다음, 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`에 고정한 정확한 버전을 실행합니다. 번들된 사이드카, 체크섬을 검증한 다운로드, 또는 그 버전을 보고하는 시스템 `typst` 중 하나입니다. 선택한 `.typ` 메인 문서를 사람이 읽을 수 있는 진단 메시지와 명시적인 PDF 출력 경로로 컴파일합니다. 자동 컴파일이 켜져 있으면 Rust가 대신 프로젝트마다 `typst watch` 프로세스를 하나씩 유지합니다(`src-tauri/src/typst_watch.rs`). 해석 방식, 고정 버전, 그에 맞는 Tinymist는 데스크톱 저장소의 `docs/typst-toolchain.md`에 있습니다.
5. Markdown은 `.md`/`.markdown` 파일에 대해 Pandoc을 직접 호출하며, 명시적인 출력 경로와 `--pdf-engine=<absolute bundled Tectonic path>`를 사용합니다. Pandoc 매뉴얼은 PDF 엔진의 전체 경로를 지정하는 방식을 명시적으로 지원합니다. 이를 암묵적인 시스템 `pdflatex`로 바꾸지 마세요. 패키지로 배포된 Oleafly는 선언되지 않은 TeX 설치에 의존해서는 안 되기 때문입니다. 프로세스는 프로젝트 루트를 작업 디렉터리로 실행하므로, 상대 경로의 이미지, 참고문헌 파일, CSL 파일이 루트 문서와 하위 폴더의 메인 문서 모두에서 동작합니다.

Tauri의 [사이드카 문서](https://v2.tauri.app/develop/sidecar/)는 타깃 트리플 접미사가 붙은 `bundle.externalBin` 입력을 정의하고, 패키지된 사이드카를 런타임에 접미사 없는 이름으로 노출합니다. Oleafly의 Pandoc 어댑터는 Tauri 데스크톱 번들 구조에 맞게, 애플리케이션 실행 파일 옆에 있는 패키지된 Tectonic 실행 파일을 찾습니다. 단위 테스트는 macOS 앱 번들과 Cargo debug/release 후보 경로를 다루고, 릴리스 워크플로는 모든 타깃에서 스테이징된 접미사 없는 형제 파일을 검사합니다.

Tectonic, Biber, Typst, 언어 서버 다운로드는 버전과 체크섬이 고정되어 있습니다. 가져오기 스크립트는 아카이브 구조를 검증하고, 검토를 거친 실행 파일이나 리소스 경로만 추출합니다. CI와 릴리스 빌드도 같은 스크립트를 씁니다.

6. 모든 엔진은 정규화된 로그와 오류 이벤트를 스트리밍합니다. Rust는 컴파일 메타데이터를 JSON IPC로 돌려줍니다. PDF 자체는 결과에 base64로 넣지 않고 별도의 원시 바이너리 IPC로 가져옵니다.
7. 프런트엔드는 pdf.js로 PDF 바이트를 렌더링하고, 정규화된 진단을 CodeMirror에 게시합니다.

엔진 디스크립터는 컴파일 정책과 함께 서식·소스 프리플라이트 프로필, 기능·내보내기·템플릿 종류 집합을 담고 있습니다. 프런트엔드는 확장자로 추측하지 않고, 실패 시 차단하는 방식(fail-closed)의 files 스토어 디스크립터를 사용합니다. [문서 엔진 매트릭스](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 프로젝트를 거부하고, 어시스턴트의 그림 도구는 CeTZ 캔버스나 fletcher 다이어그램 같은 Typst 스니펫을 대신 `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`을 구현하고, 사실에 부합하는 기능을 노출하고, 체크섬이 고정된 사이드카 가져오기와 스모크 경로를 추가한 다음, 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 기기 흐름은 OAuth 엔드포인트가 CORS를 허용하지 않기 때문에 Rust 쪽(`src-tauri/src/github.rs`)에서 실행됩니다. API 호출(api.github.com)은 프런트엔드에서 이루어집니다.

## 코딩 스타일

- TypeScript: 이미 있는 코드를 따릅니다. 요청이 없으면 주석을 쓰지 않습니다. `noUnusedLocals`/`noUnusedParameters`를 지킵니다.
- Rust: 관용적으로 작성하고, 명령은 작게 유지하며, 오류 문자열은 친절하게 씁니다.
- UI: Tailwind v4와 Geist 토큰을 사용합니다. `Button`, `Tooltip`, `Select` 기본 컴포넌트를 재사용합니다.

## 릴리스

패키징 대상은 macOS Apple Silicon, Windows x64, Linux x64, Linux ARM64입니다. 각 빌드는 컴파일러 사이드카와 번들된 언어 서버 리소스를 가져와 검사합니다. 릴리스 빌드는 macOS의 Apple 서명과 공증, Windows의 Azure Artifact Signing을 지원합니다. [릴리스](/docs/engineering/releasing/)와 사용자용 [설치](/docs/install/)를 참고하세요.
