콘텐츠로 이동
Oleaflyv0.4.12

Oleafly 데스크톱 저장소를 설정하고, 고정된 사이드카를 가져와 앱을 실행하고, 주요 확장 지점을 이해합니다.

Oleafly는 Tauri 2 (새 탭에서 열림) 데스크톱 앱입니다. 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/를 수정하기 전에 프런트엔드 아키텍처를 읽어 보세요. 포트 패턴, 기여 레지스트리, 별칭 연결 방식을 설명합니다.

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

터미널 창
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

풀 리퀘스트를 열기 전에 해당하는 로컬 검사를 실행하세요.

터미널 창
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 (새 탭에서 열림)를 참고하세요.

터미널 창
pnpm test:e2e:app # builds + launches the app, runs Playwright, tears down
컴파일이 앱 안에서 이동하는 방식프런트엔드가 Tauri IPC로 compileProject를 호출합니다. Rust에서는 DocumentEngine이 프로젝트의 엔진을 고릅니다. Tectonic, latexmk, Typst, 또는 Pandoc과 Tectonic입니다. PDF는 원시 바이너리 IPC로 pdf.js 뷰어에 돌아오고, 스트리밍된 로그 이벤트는 CodeMirror의 진단이 됩니다.프런트엔드Rust, src-tauri컴파일 요청compileProject()pdf.js 뷰어PDF 표시CodeMirror진단DocumentEngine엔진 선택TectoniclatexmkTypstPandoc, TectonicTauri IPCPDF 바이트스트리밍된 로그컴파일이 앱 안에서 이동하는 방식프런트엔드가 Tauri IPC로 compileProject를 호출합니다. Rust에서는 DocumentEngine이 프로젝트의 엔진을 고릅니다. Tectonic, latexmk, Typst, 또는 Pandoc과 Tectonic입니다. PDF는 원시 바이너리 IPC로 pdf.js 뷰어에 돌아오고, 스트리밍된 로그 이벤트는 CodeMirror의 진단이 됩니다.프런트엔드compileProject()DocumentEngineRust에서엔진Tectonic, latexmk,Typst 또는 Pandocpdf.jsPDF 표시CodeMirror진단Tauri IPCPDF로그
프런트엔드가 Rust에 컴파일을 요청하고, DocumentEngine이 프로젝트의 엔진을 실행합니다. PDF는 바이너리 IPC로 돌아오고, 스트리밍된 로그는 진단으로 바뀝니다.
  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의 사이드카 문서 (새 탭에서 열림)는 타깃 트리플 접미사가 붙은 bundle.externalBin 입력을 정의하고, 패키지된 사이드카를 런타임에 접미사 없는 이름으로 노출합니다. Oleafly의 Pandoc 어댑터는 Tauri 데스크톱 번들 구조에 맞게, 애플리케이션 실행 파일 옆에 있는 패키지된 Tectonic 실행 파일을 찾습니다. 단위 테스트는 macOS 앱 번들과 Cargo debug/release 후보 경로를 다루고, 릴리스 워크플로는 모든 타깃에서 스테이징된 접미사 없는 형제 파일을 검사합니다.

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

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

엔진 디스크립터는 컴파일 정책과 함께 서식·소스 프리플라이트 프로필, 기능·내보내기·템플릿 종류 집합을 담고 있습니다. 프런트엔드는 확장자로 추측하지 않고, 실패 시 차단하는 방식(fail-closed)의 files 스토어 디스크립터를 사용합니다. 문서 엔진 매트릭스 (새 탭에서 열림)를 참고하세요.

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/에 등록합니다 (프런트엔드 아키텍처 참고).

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을 지원합니다. 릴리스와 사용자용 설치를 참고하세요.

이미지 미리보기

AI 답변을 불러오지 못했습니다

다시 시도하거나 문서를 검색하세요.