Desenvolvimento
Configure o repositório do aplicativo de desktop Oleafly, baixe os sidecars fixados, execute o aplicativo e conheça os principais pontos de extensão.
O Oleafly é um aplicativo de desktop em Tauri 2 (abre em uma nova guia). O frontend em React e TypeScript conversa com o Rust por IPC do Tauri. O Rust é responsável pelos arquivos de projeto, pela compilação, pelos segredos, pelo roteamento de MCP e pelas requisições a provedores de IA.
Estrutura do repositório
Seção intitulada “Estrutura do repositório”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/O frontend é um workspace pnpm. As funcionalidades reutilizáveis ficam em packages/* atrás de portas injetadas, e o shell do aplicativo conecta tudo. Leia Arquitetura do frontend antes de mexer em packages/: o documento cobre o padrão de portas, o registro de contribuições e a ligação dos aliases.
Pré-requisitos
Seção intitulada “Pré-requisitos”- Node.js 22.13+ e pnpm 11.9+ (a versão exata do pnpm é declarada no
package.json) - Rust (stable) por meio do rustup (abre em uma nova guia)
- Dependências de sistema do Tauri 2 (abre em uma nova guia) para o seu sistema operacional
- Opcional durante a configuração: pandoc (abre em uma nova guia) para a compilação de PDF a partir de Markdown e a exportação de documentos (o aplicativo pode instalar a versão fixada dele sob demanda)
Primeira execução
Seção intitulada “Primeira execução”pnpm install./scripts/fetch-tectonic.sh all./scripts/fetch-biber.sh all./scripts/fetch-typst.sh allpnpm language-servers:fetchpnpm tauri devPara uma única plataforma, passe a tripla de destino do Rust para cada script shell de download. Use rustc -vV para descobrir a tripla do host. O comando de servidores de linguagem seleciona o host atual, a menos que você passe um destino pelo script subjacente dele.
Dia a dia
Seção intitulada “Dia a dia”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 bundleVerificações antes de abrir um PR
Seção intitulada “Verificações antes de abrir um PR”Execute as verificações locais relevantes antes de abrir um pull request:
pnpm build # frontend typecheck (noUnusedLocals/Parameters on)pnpm test # vitest across src/ and packages/pnpm audit --prod --audit-level high # registry-backed npm advisory checkcargo check --workspace --all-targets # Rust workspace compilescargo deny --manifest-path src-tauri/Cargo.toml check # Rust advisories, licenses, and sourcesOs dois comandos de auditoria exigem acesso a registro/rede. O CI registra os resultados atuais deles a cada mudança de código. Uma execução local offline não pode certificar que o grafo de dependências está livre de avisos de segurança.
Para mudanças visíveis ao usuário, execute também a suíte ponta a ponta contra o aplicativo e o compilador reais. Veja o e2e/README.md (abre em uma nova guia).
pnpm test:e2e:app # builds + launches the app, runs Playwright, tears downComo funciona uma compilação
Seção intitulada “Como funciona uma compilação”- O frontend carrega o descritor
project_enginedo backend e as flags de capacidade dele, então chamacompileProject(projectId, mainDoc, offline)por IPC do Tauri. - O Rust faz o despacho por meio de
DocumentEngine. O código de UI não deve inferir o comportamento do motor a partir de um nome de arquivo. - O LaTeX usa o Tectonic embutido por padrão. Um projeto pode, em vez disso, escolher pdfLaTeX, XeLaTeX ou LuaLaTeX por meio do
latexmk. Uma instalação TeX do sistema completa tem prioridade sobre o TinyTeX gerenciado do Oleafly. O detector compartilhado exige os compiladores principais, olatexmk, okpsewhiche o Biber antes de conceder essa prioridade. - O Typst executa exatamente a versão que o projeto fixa no
project.json: o sidecar embutido, um download verificado por checksum ou umtypstdo sistema que informa essa versão. Ele compila o documento principal.typselecionado com diagnósticos legíveis por humanos e um caminho explícito de saída em PDF. Com a Compilação automática ativada, o Rust mantém, em vez disso, um processotypst watchpor projeto (src-tauri/src/typst_watch.rs). Odocs/typst-toolchain.mddo repositório do aplicativo de desktop cobre a resolução, as fixações de versão e o Tinymist correspondente. - O Markdown invoca o Pandoc diretamente sobre
.md/.markdown, com um caminho de saída explícito e--pdf-engine=<absolute bundled Tectonic path>. O manual do Pandoc apoia explicitamente um caminho completo para o motor de PDF. Não substitua isso por umpdflateximplícito do sistema, porque o Oleafly empacotado não deve depender de uma instalação TeX não declarada. O processo executa com a raiz do projeto como diretório de trabalho, de modo que imagens, arquivos de bibliografia e arquivos CSL relativos funcionem tanto para documentos principais na raiz quanto aninhados.
A documentação de sidecars do Tauri (abre em uma nova guia) define as entradas de bundle.externalBin com sufixos de tripla de destino e expõe o sidecar empacotado sob o nome sem sufixo em tempo de execução. O adaptador Pandoc do Oleafly resolve esse executável Tectonic empacotado ao lado do executável do aplicativo, o que corresponde ao layout de empacotamento de desktop do Tauri. Testes de unidade cobrem os candidatos de app bundle do macOS e de debug/release do Cargo, enquanto o fluxo de trabalho de release inspeciona o irmão sem sufixo preparado em cada destino.
Os downloads de Tectonic, Biber, Typst e servidores de linguagem têm versão e checksum fixados. Os scripts de download deles validam a estrutura do arquivo compactado e extraem apenas os caminhos de executável ou recurso revisados. O CI e os builds de release usam os mesmos scripts.
- Todos os motores transmitem eventos normalizados de log/erro. O Rust retorna os metadados da compilação por IPC em JSON. O próprio PDF é buscado separadamente como IPC binário bruto, em vez de embutido em base64 no resultado.
- O frontend renderiza os bytes do PDF com pdf.js e publica diagnósticos normalizados no CodeMirror.
Os descritores de motor modelam a política de compilação, além de perfis de formatação/pré-verificação de fonte e conjuntos de funcionalidades/exportação/tipos de modelo. Os consumidores do frontend usam o descritor fail-closed do store de arquivos, em vez de adivinhar por extensões. Veja a matriz de motores de documento (abre em uma nova guia).
O Typst informa supports_synctex=true e supports_offline=true, com supports_isolated_compile=false. A sincronização entre fonte e PDF passa pelo Tinymist correspondente ao projeto e exige o Tinymist 0.13.30 ou posterior, então typst_toolchain::describe_project rebaixa supports_synctex para false em um projeto fixado no Typst 0.11 ou 0.12 (typst_sync::supported_for_project). O Modo offline bloqueia downloads de pacotes do Typst, então uma compilação passa a usar apenas o cache compartilhado de pacotes e a pasta typst-packages do projeto. A compilação isolada continua exclusiva do LaTeX: o caminho de figuras TikZ recusa projetos Typst, e as ferramentas de figuras do assistente renderizam trechos de Typst, como um canvas CeTZ ou um diagrama fletcher, com render_typst_snippet em vez disso. Acrescente comportamento de motor somente depois que a capacidade do backend se tornar verdadeira. Não acrescente exceções de UI baseadas em extensão.
Onde fica o estado
Seção intitulada “Onde fica o estado”- Configuração:
~/.oleafly/config.json(0600no Unix). Preferências sem segredos ficam aqui. - Segredos:
~/.oleafly/ai-secrets.jsone~/.oleafly/app-secrets.json, criptografados com o~/.oleafly/ai-secrets.key, legível somente pelo dono. O GitHub e o MCP compartilham oapp-secrets.json. Credenciais de provedores de IA usam oai-secrets.json. - Projetos:
~/.oleafly/projects/<id>/, pastas comuns com.git. - Log do aplicativo:
~/.oleafly/app.log.
Principais pontos de extensão
Seção intitulada “Principais pontos de extensão”- Adicionar um provedor de IA → atualize
crates/oleafly-agent/src/provider.rse depois espelhe os metadados de exibição dele empackages/ai-core/src/providers.ts. O teste de paridade de catálogos mantém as duas listas alinhadas. - Adicionar um comando Tauri → declare em
src-tauri/src/*.rs, registre emsrc-tauri/src/lib.rse encapsule emsrc/lib/tauri.ts. - Adicionar um motor de documento → implemente
DocumentEngineemsrc-tauri/src/document_engine.rs, exponha capacidades verdadeiras, acrescente um caminho de download/smoke test de sidecar com checksum fixado e então consuma o descritor nos controles de UI. - Adicionar um modelo de projeto → coloque uma pasta com um manifesto
template.jsonemsrc-tauri/resources/templates/(metadados gerais de modelo por motor continuam um trabalho planejado). - Adicionar uma ferramenta para a IA →
packages/ai-tools/src/tools.ts. Serviços do aplicativo de que ela precisa passam porAiToolsHostemsrc/lib/ai-tools.ts. - Adicionar uma aba da rail / comando da paleta ou do omnibar / conjunto de ferramentas de IA → registre em
src/contributions/(veja Arquitetura do frontend).
Detalhes internos de sincronização e do GitHub
Seção intitulada “Detalhes internos de sincronização e do GitHub”O fluxo de dispositivo OAuth executa no lado do servidor, em Rust (src-tauri/src/github.rs), porque os endpoints OAuth não têm CORS habilitado. As chamadas de API (api.github.com) acontecem a partir do frontend.
Estilo de código
Seção intitulada “Estilo de código”- TypeScript: siga o que já existe. Sem comentários, a menos que solicitado. Respeite
noUnusedLocals/noUnusedParameters. - Rust: idiomático, comandos pequenos, mensagens de erro amigáveis.
- UI: Tailwind v4 + tokens Geist. Reutilize os primitivos
Button,TooltipeSelect.
Lançamento de versões
Seção intitulada “Lançamento de versões”O empacotamento visa macOS Apple Silicon, Windows x64, Linux x64 e Linux ARM64. Cada build baixa e verifica os sidecars de compilador e o recurso de servidores de linguagem embutido. Builds de release suportam assinatura da Apple e notarização no macOS e Azure Artifact Signing no Windows. Veja lançamento de versões e instalação para o usuário.